Imágenes SVG en fpdf2: conserva los trazados en tu PDF de Python

Usa pdf.image("logo.svg", x=20, y=20, w=60) para colocar un SVG en un documento de fpdf2. La geometría SVG compatible se convierte en trazados de dibujo del PDF. No necesitas renderizar primero el logotipo como PNG. La documentación oficial de SVG describe esta vía directa y sus límites.

Si aún no conoces el formato, la guía de archivos SVG explica los trazados y los contenedores de imágenes. Incluso una importación correcta requiere comprobaciones. El archivo puede contener píxeles incrustados, depender de funciones que el importador no reproduce o tener espacio vacío alrededor del diseño. Esta guía crea un pequeño logotipo original, lo coloca con un tamaño explícito y comprueba el PDF resultante. Conserva el original vectorial si dispones de uno; recuperar un diseño a partir de PNG o JPG es un paso previo independiente.

Empieza con un SVG conocido y una versión fija de fpdf2

Ejecutamos el ejemplo con Python 3.12 y fpdf2 2.8.8. Esa es la versión probada; no implica que todas las versiones posteriores se comporten igual. La página oficial del paquete en PyPI documenta la instalación con el nombre de distribución fpdf2; la importación en Python es fpdf.

Usa un entorno nuevo para que el ejemplo no dependa de los paquetes de otro proyecto:

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

En Windows, activa el entorno con .venv\Scripts\activate. Guarda este emblema rectangular original como 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>

Hay dos subtrazados cerrados. El rectángulo exterior se rellena y el interior se convierte en una abertura mediante la regla de relleno evenodd. No intervienen fuentes, imágenes ni efectos, lo que facilita diagnosticar la primera prueba.

Guarda lo siguiente como place_logo.py junto al 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"))

Ejecuta python place_logo.py. Abre logo.pdf y comprueba que aparezca un marco rectangular verde azulado cerca de la esquina superior izquierda, con la página visible a través de su centro.

Distingue el lienzo SVG del logotipo pintado

El lienzo de origen tiene una proporción de 3:2: 120 unidades de ancho y 80 de alto. Con w=60, este ejemplo ocupa un lienzo de 60 × 40 mm. El diseño empieza 10 unidades del archivo de origen hacia dentro de ese lienzo, por lo que su rectángulo exterior pintado mide 50 × 30 mm y comienza en 25, 25 mm de la página. Estos cálculos corresponden a las coordenadas y la escala de este archivo de prueba.

Ese margen explica por qué medir la forma coloreada no da el mismo resultado que medir el lienzo de colocación. Si el logotipo de un cliente parece demasiado pequeño, inspecciona los márgenes del archivo de origen antes de aumentar su ancho en el PDF.

La guía de imágenes de fpdf2 explica cómo se manejan las dimensiones y la opción de conservar las proporciones dentro de un recuadro especificado. Para este primer ejemplo, establece solo el ancho. Si después proporcionas ambas dimensiones, prueba expresamente el ajuste que buscas en lugar de suponer que todos los archivos de origen tendrán las mismas proporciones.

Verifica que el PDF guardado contiene trazados

La vista previa del PDF muestra su aspecto, pero una imagen puede verse nítida con un aumento moderado. Inspecciona también el archivo. Comprobamos el ejemplo aislado 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"))

Nuestra salida indicó cero imágenes en la página. El contenido descodificado contenía contornos rectangulares expresados mediante operaciones de movimiento, línea y cierre de trazado, seguidas de f*, la operación de relleno par-impar. Junto con la abertura renderizada, esto respalda la conclusión de que este archivo de prueba sin imágenes conservó su geometría de dibujo en el PDF guardado.

No apliques esa conclusión a otra entrada sin comprobarla. Un informe puede contener legítimamente fotografías en otras partes; un SVG puede contener una imagen. El diagnóstico de raster incrustado ayuda a distinguir un logotipo formado por trazados de un mapa de bits envuelto en código SVG. Los PDF más complejos también pueden colocar contenido de dibujo dentro de objetos referenciados, así que el breve script anterior es un punto de partida para este archivo de prueba aislado, no una auditoría universal de PDF.

Diagnostica los elementos ausentes con tu versión instalada

Empieza ejecutando el pequeño emblema anterior. Si funciona mientras que tu logotipo de producción falla, habrás acotado el problema al diseño de origen o a las funciones que utiliza. Conserva el original y simplifica una copia, eliminando una función cada vez.

Las respuestas antiguas requieren cuidado en este caso. Nuestra prueba independiente con 2.8.8, que contenía un elemento <text> sencillo, produjo texto HELLO extraíble, y un rectángulo con un degradado lineal básico se exportó correctamente. Estas comprobaciones limitadas no demuestran compatibilidad completa con texto, fuentes, CSS o degradados SVG. Sí muestran por qué una afirmación antigua de que ningún texto SVG o ningún degradado es compatible puede llevarte a rasterizar sin necesidad.

La lista actual de funciones SVG sigue indicando limitaciones como marcadores, patrones, texto sobre un trazado y CSS complejo o externo. Mantén visibles las advertencias del importador durante el diagnóstico y compara la página guardada con el archivo de origen. Un registro sin advertencias no demuestra por sí solo que se hayan conservado todos los elementos visuales.

Recurre a raster cuando el resultado lo requiera

Si un efecto no puede reproducirse en el proceso que has elegido, decide si conservar su aspecto importa más que mantener la geometría. Un PNG renderizado puede ser adecuado para esa parte del documento. Compruébalo al tamaño físico final y describe el resultado con precisión; incrustar una representación raster no conserva los trazados originales.

Para un logotipo de marca, puede ser mejor usar letras convertidas a contornos y aprobadas o una exportación vectorial más sencilla. Para texto editable del documento, conserva la gestión de fuentes y texto en el flujo de trabajo del documento. Trazar una captura de pantalla de una frase no recupera su tipografía ni la convierte en texto seleccionable.

Si tu código PDF actual usa otra biblioteca de Python, el flujo de trabajo SVG de ReportLab tiene sus propias comprobaciones de importación y tamaño. Cambiar de biblioteca es una decisión de implementación independiente, así que prueba la función que realmente causa problemas antes de reconstruir el documento.

Prepara los diseños disponibles solo en raster antes del paso de PDF

Cuando solo queda un logotipo PNG o JPG, el vectorizador de logotipos de PerfectVector puede preparar un SVG candidato antes de importarlo con fpdf2. Compara los contornos, las aberturas pequeñas y las regiones de color con el archivo de origen y después somete el candidato a las mismas comprobaciones de colocación y PDF.

Usa el original vectorial si está disponible. Las letras exactas de una marca pueden requerir volver a escribirlas o corregirlas manualmente; la guía de vectorización de logotipos explica esa elección. El emblema de este artículo es un SVG original escrito a mano, no el resultado medido de una conversión de PerfectVector. PerfectVector prepara el diseño, mientras que fpdf2 controla su colocación en el PDF.

Preguntas frecuentes

¿Puede fpdf2 insertar un SVG directamente? Sí. Pasa el archivo SVG al método de imagen y establece su colocación y tamaño. La geometría compatible puede convertirse en trazados PDF, pero inspecciona el archivo exportado y el aspecto de tu propio diseño.

¿Es compatible fpdf2 con el texto SVG? Nuestra prueba de texto básico funcionó con fpdf2 2.8.8. Eso no garantiza todas las fuentes, funciones de composición o estructuras de texto sobre trazados. Comprueba tu versión instalada y prueba las letras que realmente usa tu documento.

¿Por qué una imagen de 60 mm parece más estrecha que 60 mm? El tamaño solicitado se aplica al lienzo de colocación. Los márgenes vacíos dentro del SVG siguen formando parte de ese lienzo, por lo que la forma pintada puede ser más estrecha.

¿Debo convertir mi logotipo PNG a SVG antes de añadirlo? Solo si necesitas trazados editables y el diseño es adecuado para el trazado. Conserva las fotografías como imágenes raster y usa un logotipo vectorial original cuando exista. Comprueba cualquier candidato trazado antes de insertarlo.

Fuentes

1. fpdf2 — SVG — Documenta la inserción directa de SVG, las funciones compatibles y los registros de advertencias.
2. fpdf2 — Imágenes — Explica la colocación de imágenes, las dimensiones y el ajuste de la relación de aspecto.
3. fpdf2 — Paquete de PyPI — Identifica la distribución instalable y su convención de importación en Python.

¿Solo tienes un logotipo raster? Prepara un SVG candidato con PerfectVector, inspecciona sus contornos y aberturas y después colócalo al tamaño necesario con fpdf2 y comprueba el PDF guardado.