> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

# CairoSVG: esporta PDF e PNG alla dimensione giusta

> Converti grafica SVG con CairoSVG, scegli larghezza o scala, comprendi DPI e dimensioni del contenitore e verifica pixel PNG e pagina PDF prima della consegna.

Source: https://perfectvector.com/it/blog/cairosvg-output-size

Language: it
Author: Irene Kim
Published: 2026-09-22T08:00:00+09:00
Updated: 2026-09-29T08:00:00+09:00

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:

```bash
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](https://cairosvg.org/documentation/#installation).

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.

```xml
<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`:

```python
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:

```bash
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](https://cairosvg.org/documentation/#python) 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.

![Illustrazione di un emblema geometrico che si dirama in due esportazioni con proporzioni simili su tele di dimensioni diverse](https://perfectvector.com/blog/cairosvg-output-size/output-sizing.webp)

*Illustrazione della scelta di esportazione: mantieni un originale vettoriale, poi scegli le dimensioni necessarie per ogni consegna. I risultati misurati di CairoSVG sono elencati qui sotto.*

## Scegli il controllo adatto al problema

Le opzioni con nomi simili rispondono a domande diverse. Il [riferimento di dimensionamento di CairoSVG](https://cairosvg.org/documentation/#command-line) distingue il contenitore genitore dalle dimensioni di output richieste.

| Requisito                                                  | Opzione Python                  | Opzione CLI           | Cosa controllare                                              |
| ---------------------------------------------------------- | ------------------------------- | --------------------- | ------------------------------------------------------------- |
| Crea un PNG largo esattamente 480 pixel                    | `output_width=480`              | `--output-width 480`  | Altezza e proporzioni della grafica                           |
| Raddoppia le dimensioni di output risolte                  | `scale=2`                       | `--scale 2`           | Entrambe le dimensioni raddoppiate                            |
| Risolvi larghezza o altezza radice espresse in percentuale | `parent_width`, `parent_height` | `--width`, `--height` | Percentuale del contenitore fornito                           |
| Interpreta unità fisiche come i pollici                    | `dpi`                           | `--dpi`               | Dimensioni in pixel PNG e dimensione fisica PDF separatamente |

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

| Impostazioni       | Dimensioni PNG | Dimensioni pagina PDF |
| ------------------ | -------------- | --------------------- |
| Predefinite        | 240 × 120 px   | 180 × 90 pt           |
| `output_width=480` | 480 × 240 px   | 360 × 180 pt          |
| `scale=2`          | 480 × 240 px   | 360 × 180 pt          |
| `dpi=192`          | 240 × 120 px   | 90 × 45 pt            |

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:

```python
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](https://perfectvector.com/it/blog/reportlab-svg) tratta la costruzione diretta di PDF; i [controlli di risorse e dimensionamento di WeasyPrint](https://perfectvector.com/it/blog/weasyprint-svg-image-pdf) 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:

```python
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`](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) 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](https://cairosvg.org/svg_support/) 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](https://perfectvector.com/it/blog/svg-contains-raster-image) 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](https://perfectvector.com/it/blog/how-to-vectorize-a-logo) 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](https://perfectvector.com/it/vectorize-logo), 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](https://cairosvg.org/documentation/) — Descrive installazione, API di conversione, controlli di dimensionamento e limiti di rendering.
2. [Supporto SVG 1.1 di CairoSVG](https://cairosvg.org/svg_support/) — Spiega conservazione del vettore, immagini incorporate e funzionalità non supportate.
3. [Riferimento pypdf PageObject](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) — Documenta le interfacce dei riquadri di pagina e delle immagini usate per esaminare il PDF.

## Explore

- [Read the HTML article](https://perfectvector.com/it/blog/cairosvg-output-size)
- [Immagini SVG con fpdf2: tracciati nel PDF Python](https://perfectvector.com/it/blog/fpdf2-svg-image.md)
- [PDFKit SVG: inserisci un logo senza rasterizzarlo](https://perfectvector.com/it/blog/pdfkit-svg.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
