CairoSVG: exporte PDF e PNG no tamanho certo

Use cairosvg.svg2png() para uma exportação raster e cairosvg.svg2pdf() para um PDF. Para uma largura PNG específica, defina output_width; para uma ampliação proporcional, use scale. parent_width fornece o contêiner usado para resolver dimensões percentuais. dpi controla a relação entre pixels e unidades físicas, portanto mudá-lo pode afetar os tamanhos PNG e PDF de formas diferentes.

O exemplo abaixo começa com um pequeno emblema SVG e verifica os arquivos produzidos por cada configuração. Ele atende a designers automatizando exportações de logos e desenvolvedores preparando arte para documentos. O CairoSVG renderiza conteúdo SVG existente. Não traça um logo PNG em traçados editáveis.

Comece com um SVG autossuficiente

Executamos estes exemplos com Python 3.12.11 e CairoSVG 2.9.1. Instale o conversor com versão fixada em um ambiente do projeto:

python -m pip install "CairoSVG==2.9.1"

O CairoSVG também precisa da biblioteca nativa Cairo. Se a instalação ou importação falhar, siga as notas por sistema operacional em sua documentação de instalação.

Salve este emblema original de três traçados como emblem.svg. A abertura quadrada facilita perceber uma regra de preenchimento ausente, e a barra estreita oferece um ponto de verificação de pequenos detalhes. Esta é arte de demonstração criada manualmente, não uma conversão do 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>

As dimensões da raiz descrevem a viewport de saída. O viewBox descreve o retângulo interno de coordenadas da arte. Aqui, ambos têm a mesma proporção 2:1. Mantenha essa relação deliberada ao adaptar o exemplo ao seu logo.

Exporte um original no tamanho necessário

Salve isto como export_emblem.py ao lado do SVG e execute 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",
)

Nosso PNG tinha 480 × 240 pixels. A página PDF tinha 180 × 90 pontos, equivalentes a 2.5 × 1.25 polegadas. Essas são medições do exemplo fornecido, não dimensões esperadas de todo SVG.

Os equivalentes por linha de comando são:

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

A referência de API e linha de comando do CairoSVG documenta nomes de arquivo de entrada por url, bytes SVG por bytestring e saída em arquivo por write_to. Na CLI, a extensão do arquivo de saída seleciona o formato.

Escolha o controle adequado ao problema

As opções com nomes semelhantes respondem a perguntas diferentes. A referência de tamanho do CairoSVG separa o contêiner pai das dimensões de saída solicitadas.

Para nosso SVG original dimensionado em pixels, executamos cada opção independentemente:

A última linha é a armadilha: dobrar o DPI não deu mais pixels PNG a este SVG dimensionado em pixels. Fez as mesmas dimensões em pixels ocuparem menos espaço físico no PDF. Use uma dimensão de saída quando o requisito de entrega for uma contagem de pixels.

Fornecer ambas as dimensões de saída define o retângulo da área de desenho; não garante uma caixa ajustada aos limites do logo. As regras de proporção do SVG e qualquer área vazia dentro de seu viewBox ainda importam. Comece com uma dimensão de saída quando quiser as proporções originais e inspecione o resultado.

Dimensões percentuais precisam de um contêiner pai

Para uma cópia do exemplo cuja raiz usa width="50%" height="50%", esta chamada fornece um contêiner pai de 960 × 480 pixels:

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

Nossa saída tinha 480 × 240 pixels: metade da largura do pai e metade de sua altura. Isso explica por que parent_width=480 não é intercambiável com output_width=480.

Se o CairoSVG informar que o tamanho SVG é indefinido, inspecione primeiro as dimensões da raiz. Dê ao documento dimensões positivas adequadas ao uso ou forneça dimensões do pai quando porcentagens dependerem delas. Não deduza o tamanho pretendido da página pelo tamanho em que um navegador acaba exibindo a arte.

Dimensões físicas se comportam diferente

Mude a raiz original para width="2.5in" height="1.25in", mantendo seu viewBox. Em nosso teste, dpi=96 produziu um PNG de 240 × 120, e dpi=192 produziu um de 480 × 240. Ambos os PDFs permaneceram 180 × 90 pontos.

Aqui, o SVG original define um tamanho físico, portanto mais pixels por polegada aumentam a resolução raster preservando o tamanho físico da página PDF. O mesmo princípio permite que uma página criada deliberadamente use milímetros ou polegadas. Confira a caixa de página do PDF exportado em vez de presumir que uma grande quantidade de pixels signifique uma página A4 ou carta.

Se o logo precisar ficar dentro de um relatório com texto, margens e vários elementos, use uma etapa de layout de documento. Nosso guia de inserção SVG no ReportLab aborda construção direta de PDF; as verificações de recursos e tamanho do WeasyPrint abordam documentos HTML.

Verifique a exportação, incluindo o que permaneceu vetorial

Lemos os cabeçalhos PNG com Pillow e as caixas de página e fluxos de conteúdo PDF com pypdf 6.10.0. Cada um dos quatro PDFs gerados a partir do SVG dimensionado em pixels continha operações de traçados de desenho e zero imagens de página. Isso confirma geometria vetorial para este exemplo simples sem imagens. Não estabelece fidelidade completa para qualquer SVG.

Para conferir suas próprias dimensões de saída, instale pillow e pypdf no mesmo ambiente e execute:

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

A referência de PageObject descreve mediabox e images. A contagem de imagens é um diagnóstico útil, mas não prova que todas as formas, fontes ou efeitos sobreviveram corretamente.

Antes da entrega:

1. Abra o PNG e o PDF e compare o emblema com o SVG. Confira sua abertura, triângulo, barra e margens.
2. Verifique as dimensões em pixels PNG e as dimensões físicas PDF independentemente.
3. Inspecione a arte no tamanho pretendido de uso, incluindo espaços estreitos e pequenos detalhes.
4. Guarde o SVG original e repita estas verificações após mudá-lo ou atualizar o conversor.

A página de suporte SVG do CairoSVG informa que a saída vetorial é preservada quando possível. Imagens raster incorporadas permanecem conteúdo raster. Se seu arquivo contém um PNG em um invólucro SVG, o diagnóstico de imagens incorporadas ajuda a identificá-lo antes de exportar.

O CairoSVG é um renderizador estático. Animação, scripts, layout avançado de texto e muitos filtros ficam fora de seu fluxo compatível. Sua documentação lista apenas feOffset, feBlend e feFlood como filtros suportados. Para arte que depende de outros efeitos, compare o resultado cuidadosamente ou exporte por um aplicativo que suporte esses recursos. Uma chamada de conversão bem-sucedida, sozinha, é insuficiente.

Recupere um original vetorial apenas quando a imagem original precisar

Se seu logo existe apenas como PNG ou JPG, o PerfectVector pode fornecer a etapa anterior de raster para SVG antes de o CairoSVG exportá-lo. Confira as formas recuperadas, as pequenas aberturas e as letras da marca em um editor e salve um original SVG autossuficiente. Nosso fluxo de vetorização de logos explica essa inspeção.

Um SVG editável existente pode seguir direto para a exportação. Convertê-lo em PNG e traçá-lo novamente descartaria geometria útil de origem. Fotos podem permanecer imagens raster quando esse for o conteúdo pretendido.

Para um logo apenas raster, experimente sua própria imagem no PerfectVector, inspecione os contornos e as aberturas do SVG e verifique as dimensões em pixels e o tamanho físico da página de suas exportações CairoSVG.

Perguntas frequentes

Por que mudar o DPI deixa meu PNG do mesmo tamanho? Se a raiz SVG usa dimensões em pixels, mudar o DPI não necessariamente muda a contagem de pixels PNG. Neste exemplo, um SVG de 240 por 120 pixels manteve esse tamanho com 192 DPI. Use output_width ou scale quando precisar de mais pixels de saída.

Largura do pai é o mesmo que largura de saída? Não. parent_width fornece o contêiner usado para resolver dimensões percentuais. output_width solicita a largura final de saída. Uma largura de raiz de 50% com parent_width de 960 resultou em 480 pixels no exemplo.

O CairoSVG sempre cria um PDF inteiramente vetorial? Não. O CairoSVG preserva a saída vetorial quando possível, mas um SVG pode incluir imagens raster e recursos incompatíveis. Inspecione o conteúdo e a aparência do PDF em vez de tratar a extensão do arquivo como prova.

Fontes

1. Documentação do CairoSVG — Descreve instalação, APIs de conversão, controles de tamanho e limitações de renderização.
2. Suporte SVG 1.1 do CairoSVG — Explica preservação vetorial, imagens incorporadas e recursos incompatíveis.
3. Referência de PageObject do pypdf — Documenta as interfaces de caixa de página e imagem usadas para inspecionar o PDF.