CairoSVG : exporte SVG en PDF et PNG à la bonne taille

Utilise cairosvg.svg2png() pour un export matriciel et cairosvg.svg2pdf() pour un PDF. Pour une largeur PNG précise, définis output_width ; pour un agrandissement proportionnel, utilise scale. parent_width fournit le conteneur servant à résoudre les dimensions en pourcentage. dpi contrôle la relation entre pixels et unités physiques : le modifier peut donc influencer différemment les tailles PNG et PDF.

L’exemple ci-dessous part d’un petit emblème SVG et vérifie les fichiers produits par chaque réglage. Il convient aux designers automatisant les exports de logos et aux développeurs préparant des illustrations pour des documents. CairoSVG effectue le rendu de contenu SVG existant. Il ne vectorise pas un logo PNG en tracés modifiables.

Pars d’un SVG autonome

Nous avons exécuté ces exemples avec Python 3.12.11 et CairoSVG 2.9.1. Installe cette version précise du convertisseur dans un environnement de projet :

python -m pip install "CairoSVG==2.9.1"

CairoSVG nécessite aussi la bibliothèque native Cairo. Si l’installation ou l’importation échoue, suis les notes propres à ton système dans sa documentation d’installation.

Enregistre cet emblème original à trois tracés sous emblem.svg. L’ouverture carrée permet de remarquer facilement une règle de remplissage absente, et la barre étroite fournit un repère pour les petits détails. Cette illustration de démonstration est créée à la main, pas par une conversion 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>

Les dimensions racines décrivent la zone d’affichage de sortie. Le viewBox décrit le rectangle de coordonnées interne de l’illustration. Ici, les deux ont le même rapport 2:1. Maintiens délibérément cette relation lorsque tu adaptes l’exemple à ton logo.

Exporte un original à la taille nécessaire

Enregistre ceci sous export_emblem.py à côté du SVG, puis exécute 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",
)

Notre PNG mesurait 480 × 240 pixels. La page PDF mesurait 180 × 90 points, soit 2.5 × 1.25 pouces. Ce sont des mesures de l’exemple fourni, pas des dimensions attendues pour tous les SVG.

Les équivalents en ligne de commande sont :

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

La référence de l’API et de la ligne de commande CairoSVG décrit les noms de fichiers d’entrée via url, les octets SVG via bytestring et la sortie fichier via write_to. En ligne de commande, l’extension du nom de sortie sélectionne le format.

Choisis le contrôle adapté au problème

Les options aux noms proches répondent à des questions différentes. La référence de dimensionnement CairoSVG distingue le conteneur parent des dimensions de sortie demandées.

Pour notre source dimensionnée en pixels, nous avons exécuté chaque option indépendamment :

La dernière ligne est le piège : doubler le DPI n’a pas donné davantage de pixels PNG à ce SVG dimensionné en pixels. Les mêmes dimensions en pixels occupaient moins d’espace physique dans le PDF. Utilise une dimension de sortie lorsque ton besoin de livraison porte sur un nombre de pixels.

Fournir les deux dimensions de sortie définit le rectangle de la zone de dessin ; cela ne garantit pas un cadre de logo rempli sans marges. Les règles de proportions du SVG et tout espace vide dans son viewBox comptent encore. Commence par une seule dimension de sortie pour conserver les proportions originales, puis examine le résultat.

Les dimensions en pourcentage nécessitent un parent

Pour une copie de l’exemple dont la racine utilise width="50%" height="50%", cet appel fournit un parent de 960 × 480 pixels :

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

Notre sortie mesurait 480 × 240 pixels : la moitié de la largeur et de la hauteur du parent. Cela explique pourquoi parent_width=480 n’est pas interchangeable avec output_width=480.

Si CairoSVG indique que la taille SVG est indéfinie, examine d’abord les dimensions racines. Donne au document des dimensions positives adaptées à son utilisation, ou fournis les dimensions parentes lorsque les pourcentages en dépendent. Ne déduis pas la taille de page souhaitée de la taille à laquelle un navigateur affiche par hasard l’illustration.

Les dimensions physiques se comportent différemment

Change la racine originale en width="2.5in" height="1.25in", en conservant son viewBox. Dans notre test, dpi=96 produisait un PNG de 240 × 120 et dpi=192 un PNG de 480 × 240. Les deux PDF restaient à 180 × 90 points.

Ici, la source définit une taille physique : davantage de pixels par pouce augmente donc la résolution matricielle tout en conservant la taille physique de la page PDF. Le même principe permet à une page créée délibérément d’utiliser des millimètres ou des pouces. Vérifie la boîte de page du PDF exporté au lieu de supposer qu’un grand nombre de pixels signifie une page A4 ou letter.

Si le logo doit figurer dans un rapport avec du texte, des marges et plusieurs éléments, utilise une étape de mise en page documentaire. Notre guide de placement SVG avec ReportLab traite de la construction directe de PDF ; les vérifications des ressources et dimensions WeasyPrint traitent des documents HTML.

Vérifie l’export, y compris ce qui reste vectoriel

Nous avons lu les en-têtes PNG avec Pillow et les boîtes de page et flux de contenu PDF avec pypdf 6.10.0. Chacun des quatre PDF issus de la source en pixels contenait des opérations de dessin de tracés et aucune image de page. Cela confirme une géométrie vectorielle pour cet exemple simple sans image. Cela n’établit pas une fidélité complète pour un SVG quelconque.

Pour vérifier tes propres dimensions de sortie, installe pillow et pypdf dans le même environnement et exécute :

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))

La référence PageObject décrit mediabox et images. Le nombre d’images est un diagnostic utile, mais ne peut pas prouver que chaque forme, police ou effet a été correctement conservé.

Avant livraison :

1. Ouvre le PNG et le PDF et compare l’emblème au SVG. Vérifie son ouverture, son triangle, sa barre et ses marges.
2. Vérifie indépendamment les dimensions en pixels du PNG et les dimensions physiques du PDF.
3. Examine l’illustration à sa taille d’utilisation prévue, notamment les espaces étroits et les petits détails.
4. Conserve le SVG original et répète ces vérifications après modification ou mise à niveau du convertisseur.

La page de prise en charge SVG de CairoSVG indique que la sortie vectorielle est préservée lorsque c’est possible. Les images matricielles intégrées restent matricielles. Si ton fichier contient un PNG dans une enveloppe SVG, le diagnostic des images intégrées t’aide à l’identifier avant exportation.

CairoSVG est un moteur de rendu statique. Les animations, les scripts, la mise en forme avancée du texte et de nombreux filtres sont hors de son processus pris en charge. Sa documentation liste uniquement feOffset, feBlend et feFlood comme filtres pris en charge. Pour une illustration dépendant d’autres effets, compare soigneusement le résultat ou exporte via une application prenant en charge ces fonctions. Un appel de conversion réussi ne suffit pas.

Reconstruis un original vectoriel uniquement si la source en a besoin

Si ton logo ne subsiste qu’en PNG ou JPG, PerfectVector peut fournir l’étape matriciel-vers-SVG en amont avant les exports CairoSVG. Vérifie les formes reconstruites, les petites ouvertures et le lettrage de marque dans un éditeur ; enregistre ensuite un original SVG autonome. Notre processus de vectorisation de logos explique cet examen.

Un SVG modifiable existant peut passer directement à l’export. Le convertir en PNG puis le vectoriser à nouveau éliminerait une géométrie source utile. Les photos peuvent rester matricielles si tel est le contenu souhaité.

Pour un logo uniquement matriciel, essaie ton image dans PerfectVector, examine les contours et les ouvertures du SVG, puis vérifie les dimensions en pixels et la taille physique de page de tes exports CairoSVG.

FAQ

Pourquoi changer le DPI laisse-t-il mon PNG à la même taille ? Si la racine SVG utilise des dimensions en pixels, changer le DPI ne modifie pas nécessairement le nombre de pixels PNG. Dans cet exemple, un SVG de 240 sur 120 pixels conservait cette taille à 192 DPI. Utilise output_width ou scale pour obtenir davantage de pixels en sortie.

La largeur parente est-elle identique à la largeur de sortie ? Non. parent_width fournit le conteneur servant à résoudre les dimensions en pourcentage. output_width demande la largeur finale de sortie. Une largeur racine de 50% avec parent_width de 960 donnait 480 pixels dans l’exemple.

CairoSVG crée-t-il toujours un PDF entièrement vectoriel ? Non. CairoSVG préserve la sortie vectorielle lorsque c’est possible, mais un SVG peut inclure des images matricielles et des fonctions non prises en charge. Examine le contenu et l’apparence du PDF plutôt que de considérer son extension comme une preuve.

Sources

1. Documentation CairoSVG — Décrit l’installation, les API de conversion, les contrôles de dimensionnement et les limites de rendu.
2. Prise en charge SVG 1.1 de CairoSVG — Explique la préservation vectorielle, les images intégrées et les fonctions non prises en charge.
3. Référence pypdf PageObject — Décrit les interfaces de boîte de page et d’image utilisées pour examiner le PDF.