Imagens SVG no fpdf2: traçados no PDF em Python

Use pdf.image("logo.svg", x=20, y=20, w=60) para inserir um SVG em um documento fpdf2. A geometria SVG compatível se torna traçados de desenho PDF. Você não precisa renderizar o logo em PNG primeiro. A documentação oficial de SVG descreve esse caminho direto e seus limites.

Se o próprio formato for novo para você, o guia de arquivos SVG explica traçados e contêineres de imagem. Uma importação bem-sucedida ainda precisa ser verificada. O arquivo pode conter pixels incorporados, depender de recursos que o importador não reproduz ou ter espaço vazio ao redor da arte. Este guia cria um pequeno logo original, insere-o com tamanho explícito e verifica o PDF resultante. Mantenha um original vetorial existente se você tiver um; recuperar arte de PNG ou JPG é uma etapa separada anterior.

Comece com um SVG conhecido e uma versão fixa do fpdf2

Executamos o exemplo com Python 3.12 e fpdf2 2.8.8. Essa é a versão testada, não uma promessa de que todas as versões posteriores se comportem da mesma forma. A página oficial do pacote no PyPI documenta a instalação com o nome de distribuição fpdf2; a importação Python é fpdf.

Use um ambiente novo para que o exemplo seja independente dos pacotes de outro projeto:

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

No Windows, ative o ambiente com .venv\Scripts\activate. Salve este emblema retangular 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>

Há dois subtraçados fechados. O retângulo externo é preenchido, e o interno se torna uma abertura pela regra de preenchimento evenodd. Nenhuma fonte, imagem ou efeito está envolvido, o que mantém o primeiro teste fácil de diagnosticar.

Salve o seguinte como place_logo.py ao lado do 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"))

Execute python place_logo.py. Abra logo.pdf e procure uma moldura retangular verde-petróleo perto do canto superior esquerdo, com a página aparecendo pelo centro.

Separe a área de desenho SVG do logo pintado

A área de desenho de origem tem proporção 3:2: 120 unidades de largura e 80 de altura. Com w=60, este exemplo ocupa uma área de desenho de 60 × 40 mm. A arte começa 10 unidades de origem para dentro dessa área, portanto seu retângulo externo pintado mede 50 × 30 mm, começando em 25, 25 mm na página. Esses são cálculos a partir das coordenadas e da escala deste exemplo.

Essa margem explica por que medir a forma colorida não dá a mesma resposta que medir a área de inserção. Se o logo de um cliente parecer pequeno demais, inspecione as margens de origem antes de aumentar sua largura no PDF.

O guia de imagens do fpdf2 explica o tratamento de dimensões e a opção de manter proporções dentro de uma caixa especificada. Neste primeiro exemplo, defina apenas a largura. Se depois você fornecer as duas dimensões, teste deliberadamente o ajuste desejado em vez de presumir que toda origem terá as mesmas proporções.

Verifique se o PDF salvo contém traçados

A prévia do PDF mostra a aparência, mas uma imagem pode parecer nítida com pouco zoom. Inspecione também o arquivo. Verificamos o exemplo isolado com 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"))

Nossa saída informou zero imagens de página. O conteúdo decodificado continha contornos retangulares expressos por operações de movimento, linha e fechamento de traçado, seguidos por f*, a operação de preenchimento par-ímpar. Junto da abertura renderizada, isso sustenta a conclusão de que este exemplo sem imagens permaneceu como geometria de desenho no PDF salvo.

Não aplique essa conclusão a outra entrada sem verificá-la. Um relatório pode legitimamente conter fotos em outros lugares; um SVG pode conter uma imagem. O diagnóstico de raster incorporado ajuda a distinguir um logo baseado em traçados de um bitmap envolvido em marcação SVG. PDFs mais complexos também podem colocar conteúdo de desenho dentro de objetos referenciados, portanto o pequeno script acima é um ponto de partida para este exemplo isolado, não uma auditoria universal de PDF.

Diagnostique arte ausente com a versão instalada

Comece executando o pequeno emblema acima. Se ele funcionar enquanto o logo de produção falha, você restringiu o problema à arte de origem ou aos recursos que ela usa. Preserve o original e simplifique uma cópia, um recurso por vez.

Respostas antigas exigem cuidado aqui. Nosso teste separado na versão 2.8.8, contendo um elemento <text> simples, produziu texto HELLO extraível, e um retângulo básico com gradiente linear foi exportado corretamente. Essas verificações restritas não estabelecem compatibilidade completa com texto SVG, fontes, CSS ou gradientes. Elas mostram por que uma afirmação antiga de que todo texto SVG ou todos os gradientes são incompatíveis pode levar a uma rasterização desnecessária.

A lista atual de recursos SVG ainda cita limitações como marcadores, padrões, texto em um traçado e CSS complexo ou externo. Mantenha os avisos do importador visíveis durante o diagnóstico e compare a página salva com a origem. Um registro sem avisos, sozinho, não prova que todos os recursos visuais sobreviveram.

Use uma alternativa raster quando o resultado exigir

Se um efeito não puder ser reproduzido no fluxo escolhido, decida se preservar sua aparência importa mais do que manter a geometria. Um PNG renderizado pode ser adequado para essa parte do documento. Confira-o no tamanho físico final e descreva a saída com precisão; incorporar uma renderização raster não preserva os traçados originais.

Para um logo de marca, letras aprovadas convertidas em contornos ou uma exportação vetorial mais simples podem ser uma escolha melhor. Para texto editável de documento, mantenha o tratamento de fontes e texto no fluxo do documento. Traçar uma captura de uma frase não recupera sua tipografia nem a torna texto selecionável.

Se seu código PDF existente usa outra biblioteca Python, o fluxo de SVG no ReportLab tem suas próprias verificações de importação e tamanho. Trocar de biblioteca é uma decisão de implementação separada, portanto teste o recurso que realmente causa problema antes de reconstruir o documento.

Prepare arte apenas raster antes da etapa PDF

Quando apenas um logo PNG ou JPG resta, o vetorizador de logos do PerfectVector pode preparar um candidato SVG antes de você importá-lo com fpdf2. Compare os contornos, as pequenas aberturas e as regiões de cor com a origem, depois execute o candidato pelas mesmas verificações de posicionamento e PDF.

Use o vetor original se estiver disponível. Letras exatas de uma marca podem exigir redigitação ou correção manual; o guia de vetorização de logos explica essa escolha. O emblema deste artigo é um SVG original criado manualmente, não um resultado medido de conversão do PerfectVector. O PerfectVector prepara a arte, enquanto o fpdf2 controla sua inserção no PDF.

Perguntas frequentes

O fpdf2 pode inserir um SVG diretamente? Sim. Passe o arquivo SVG para o método image e defina seu posicionamento e tamanho. A geometria compatível pode se tornar traçados PDF, mas inspecione o arquivo exportado e a aparência da sua própria arte.

O fpdf2 suporta texto SVG? Nosso teste básico de texto funcionou com fpdf2 2.8.8. Isso não garante todas as fontes, recursos de layout ou construções de texto em traçado. Confira a versão instalada e teste as letras que o documento realmente usa.

Por que uma imagem de 60 mm parece mais estreita do que 60 mm? O tamanho solicitado se aplica à área de inserção. Margens vazias dentro do SVG continuam fazendo parte dessa área, portanto a forma pintada pode ser mais estreita.

Devo converter meu logo PNG em SVG antes de adicioná-lo? Apenas se você precisar de traçados editáveis e a arte for adequada para vetorização por traçado. Mantenha fotografias como imagens raster e use um logo vetorial original quando existir. Verifique um candidato traçado antes de inseri-lo.

Fontes

1. fpdf2 — SVG — Documenta inserção direta de SVG, compatibilidade de recursos e registros de avisos.
2. fpdf2 — Imagens — Explica posicionamento de imagens, dimensões e ajuste da proporção.
3. fpdf2 — Pacote PyPI — Identifica a distribuição instalável e sua convenção de importação Python.

Só tem um logo raster? Prepare um candidato SVG com o PerfectVector, inspecione seus contornos e aberturas, insira-o no tamanho necessário com fpdf2 e confira o PDF salvo.