CairoSVG: exporta SVG a PDF y PNG al tamaño correcto

Usa cairosvg.svg2png() para una exportación raster y cairosvg.svg2pdf() para un PDF. Para un ancho PNG específico, establece output_width; para una ampliación proporcional, utiliza scale. parent_width proporciona el contenedor utilizado para resolver dimensiones porcentuales. dpi controla la relación entre píxeles y unidades físicas, así que cambiarlo puede afectar de forma distinta a los tamaños PNG y PDF.

El ejemplo siguiente empieza con un pequeño emblema SVG y comprueba los archivos producidos por cada ajuste. Sirve para diseñadores que automatizan exportaciones de logotipos y desarrolladores que preparan ilustraciones para documentos. CairoSVG renderiza contenido SVG existente. No vectoriza un logotipo PNG en trazados editables.

Empieza con un SVG autónomo

Ejecutamos estos ejemplos con Python 3.12.11 y CairoSVG 2.9.1. Instala el conversor con la versión fijada en un entorno de proyecto:

python -m pip install "CairoSVG==2.9.1"

CairoSVG también necesita la biblioteca nativa Cairo. Si falla la instalación o importación, sigue las notas para tu sistema operativo de su documentación de instalación.

Guarda este emblema original de tres trazados como emblem.svg. La abertura cuadrada facilita detectar una regla de relleno ausente y la barra estrecha proporciona un punto de comprobación de detalle pequeño. Es una ilustración de demostración creada a mano, no una conversión de 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>

Las dimensiones del elemento raíz describen el área de visualización de salida. El viewBox describe el rectángulo interno de coordenadas de la ilustración. Aquí ambos tienen la misma proporción 2:1. Mantén esa relación de forma deliberada al adaptar el ejemplo a tu logotipo.

Exporta un maestro al tamaño necesario

Guarda esto como export_emblem.py junto al SVG y ejecuta después 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",
)

Nuestro PNG tenía 480 × 240 píxeles. La página PDF medía 180 × 90 puntos, equivalentes a 2.5 × 1.25 pulgadas. Son mediciones del ejemplo suministrado, no dimensiones que debas esperar de todos los SVG.

Los equivalentes de línea de comandos son:

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

La referencia de API y línea de comandos de CairoSVG documenta nombres de archivo de entrada mediante url, bytes SVG mediante bytestring y salida a archivo mediante write_to. En la CLI, la extensión del nombre de archivo de salida selecciona el formato.

Elige el control que corresponda al problema

Las opciones con nombres parecidos responden a preguntas distintas. La referencia de tamaños de CairoSVG separa el contenedor padre de las dimensiones de salida solicitadas.

Para nuestro original dimensionado en píxeles, ejecutamos cada opción de forma independiente:

La última fila es la trampa: duplicar DPI no dio más píxeles PNG a este SVG dimensionado en píxeles. Hizo que las mismas dimensiones en píxeles ocuparan menos espacio físico en el PDF. Utiliza una dimensión de salida cuando tu requisito de entrega sea un número de píxeles.

Proporcionar ambas dimensiones de salida establece el rectángulo del lienzo; no garantiza un cuadro de logotipo completamente ocupado. Las reglas de proporción del SVG y cualquier área vacía dentro de su viewBox siguen importando. Empieza con una sola dimensión de salida cuando quieras las proporciones originales y después inspecciona el resultado.

Las dimensiones porcentuales necesitan un contenedor padre

Para una copia del ejemplo cuyo elemento raíz utilice width="50%" height="50%", esta llamada proporciona un contenedor padre de 960 × 480 píxeles:

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

Nuestra salida tenía 480 × 240 píxeles: la mitad del ancho y la mitad de la altura del contenedor padre. Esto explica por qué parent_width=480 no es intercambiable con output_width=480.

Si CairoSVG indica que el tamaño SVG no está definido, inspecciona primero las dimensiones del elemento raíz. Da al documento dimensiones positivas adecuadas para su uso o proporciona las dimensiones del contenedor padre cuando los porcentajes dependan de ellas. No deduzcas el tamaño de página previsto del tamaño al que un navegador muestre la ilustración.

Las dimensiones físicas se comportan de otra manera

Cambia el elemento raíz original a width="2.5in" height="1.25in", conservando su viewBox. En nuestra prueba, dpi=96 produjo un PNG de 240 × 120 y dpi=192 produjo un PNG de 480 × 240. Ambos PDF permanecieron en 180 × 90 puntos.

Aquí el original define un tamaño físico, así que más píxeles por pulgada aumentan la resolución raster mientras conservan el tamaño físico de página PDF. El mismo principio permite que una página creada deliberadamente utilice milímetros o pulgadas. Comprueba el cuadro de página del PDF exportado en lugar de suponer que un gran número de píxeles significa una página A4 o carta.

Si el logotipo debe estar dentro de un informe con texto, márgenes y varios elementos, utiliza un paso de composición de documentos. Nuestra guía de colocación SVG de ReportLab explica la construcción directa de PDF; las comprobaciones de recursos y tamaños de WeasyPrint cubren documentos HTML.

Verifica la exportación, incluido lo que siguió siendo vectorial

Leímos las cabeceras PNG con Pillow y los cuadros de página y flujos de contenido PDF con pypdf 6.10.0. Cada uno de los cuatro PDF del original dimensionado en píxeles contenía operaciones de trazado de dibujo y cero imágenes de página. Eso confirma geometría vectorial para este ejemplo sencillo sin imágenes. No demuestra fidelidad completa para un SVG arbitrario.

Para comprobar tus propias dimensiones de salida, instala pillow y pypdf en el mismo entorno y ejecuta:

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 referencia de PageObject describe mediabox e images. El número de imágenes es un diagnóstico útil, pero no puede demostrar que cada forma, fuente o efecto se haya conservado correctamente.

Antes de entregar:

1. Abre el PNG y el PDF y compara el emblema con el SVG. Comprueba su abertura, triángulo, barra y márgenes.
2. Verifica independientemente las dimensiones en píxeles del PNG y las dimensiones físicas del PDF.
3. Inspecciona la ilustración a su tamaño de uso previsto, incluidos huecos estrechos y detalles pequeños.
4. Conserva el SVG original y repite estas comprobaciones después de cambiarlo o actualizar el conversor.

La página de compatibilidad SVG de CairoSVG dice que la salida vectorial se conserva cuando es posible. Las imágenes raster incrustadas siguen siendo contenido raster. Si tu archivo contiene un PNG en un contenedor SVG, el diagnóstico de imágenes incrustadas te ayuda a identificarlo antes de exportar.

CairoSVG es un renderizador estático. La animación, los scripts, la disposición avanzada de texto y muchos filtros están fuera de su flujo compatible. Su documentación enumera únicamente feOffset, feBlend y feFlood como filtros compatibles. Para ilustraciones que dependan de otros efectos, compara cuidadosamente el resultado o exporta mediante una aplicación que admita esas funciones. Una llamada de conversión correcta por sí sola no basta.

Recupera un maestro vectorial solo cuando lo necesite el original

Si tu logotipo solo se conserva como PNG o JPG, PerfectVector puede proporcionar el paso previo de raster a SVG antes de que CairoSVG lo exporte. Comprueba las formas recuperadas, las aberturas pequeñas y las letras de marca en un editor y guarda después un maestro SVG autónomo. Nuestro flujo de vectorización de logotipos explica esa inspección.

Un SVG editable existente puede pasar directamente a la fase de exportación. Convertirlo a PNG y volver a vectorizarlo descartaría geometría de origen útil. Las fotos pueden seguir siendo imágenes raster cuando ese sea el contenido previsto.

Para un logotipo que solo existe como raster, prueba tu propia imagen en PerfectVector, inspecciona los contornos y aberturas del SVG y verifica después tanto las dimensiones en píxeles como el tamaño físico de página de tus exportaciones CairoSVG.

Preguntas frecuentes

¿Por qué cambiar DPI deja mi PNG del mismo tamaño? Si el elemento raíz SVG utiliza dimensiones en píxeles, cambiar DPI no cambia necesariamente el número de píxeles PNG. En este ejemplo, un SVG de 240 por 120 píxeles conservó ese tamaño a 192 DPI. Usa output_width o scale cuando necesites más píxeles de salida.

¿El ancho del contenedor padre es lo mismo que el ancho de salida? No. parent_width proporciona el contenedor utilizado para resolver dimensiones porcentuales. output_width solicita el ancho de salida final. Un ancho de raíz del 50% con parent_width de 960 se resolvió en 480 píxeles en el ejemplo.

¿CairoSVG siempre crea un PDF completamente vectorial? No. CairoSVG conserva salida vectorial cuando es posible, pero un SVG puede incluir imágenes raster y funciones incompatibles. Inspecciona el contenido y la apariencia del PDF en lugar de tratar la extensión del archivo como prueba.

Fuentes

1. Documentación de CairoSVG — Describe instalación, API de conversión, controles de tamaño y limitaciones de renderizado.
2. Compatibilidad SVG 1.1 de CairoSVG — Explica conservación vectorial, imágenes incrustadas y funciones incompatibles.
3. Referencia PageObject de pypdf — Documenta las interfaces de cuadros de página e imágenes utilizadas para inspeccionar el PDF.