CairoSVG: экспорт SVG в PDF и PNG нужного размера

Используйте cairosvg.svg2png() для растрового экспорта и cairosvg.svg2pdf() для PDF. Для конкретной ширины PNG задайте output_width; для пропорционального увеличения используйте scale. parent_width задает контейнер для вычисления процентных размеров. dpi управляет соотношением пикселей и физических единиц, поэтому его изменение может по-разному влиять на размеры PNG и PDF.

Пример ниже начинается с небольшой SVG-эмблемы и проверяет файлы, созданные каждой настройкой. Он подходит дизайнерам, автоматизирующим экспорт логотипов, и разработчикам, готовящим графику для документов. CairoSVG отрисовывает существующее содержимое SVG. Он не трассирует логотип PNG в редактируемые контуры.

Начните с автономного SVG

Мы выполняли эти примеры с Python 3.12.11 и CairoSVG 2.9.1. Установите конвертер закрепленной версии в среде проекта:

python -m pip install "CairoSVG==2.9.1"

CairoSVG также нужна нативная библиотека Cairo. Если установка или импорт не работают, следуйте примечаниям для вашей операционной системы в документации по установке.

Сохраните эту исходную эмблему из трех контуров как emblem.svg. Квадратное отверстие помогает заметить отсутствующее правило заливки, а узкая полоска дает контрольную точку для мелких деталей. Это демонстрационная графика, созданная вручную, а не преобразование 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>

Корневые размеры описывают область просмотра результата. viewBox описывает внутренний координатный прямоугольник изображения. Здесь оба имеют одинаковые пропорции 2:1. При адаптации примера к своему логотипу задавайте это соотношение намеренно.

Экспортируйте один оригинал в нужном размере

Сохраните это как export_emblem.py рядом с SVG, затем запустите 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",
)

Наш PNG имел 480 × 240 пикселей. Страница PDF имела 180 × 90 пунктов, что соответствует 2.5 × 1.25 дюйма. Это измерения предоставленного образца, а не размеры, которые следует ожидать от любого SVG.

Эквиваленты для командной строки:

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

Справка CairoSVG по API и командной строке описывает входные имена файлов через url, байты SVG через bytestring и вывод в файл через write_to. В CLI расширение имени выходного файла выбирает формат.

Выберите параметр под задачу

Параметры с похожими названиями отвечают на разные вопросы. Справка CairoSVG по размерам отделяет родительский контейнер от запрошенных выходных размеров.

Для нашего исходника с пиксельными размерами мы запускали каждый параметр независимо:

Последняя строка — ловушка: удвоение DPI не добавило пикселей PNG этому SVG с пиксельными размерами. Оно заставило те же пиксельные размеры занимать меньше физического пространства в PDF. Используйте выходной размер, когда требование передачи — количество пикселей.

Задание обоих выходных размеров определяет прямоугольник холста; оно не гарантирует плотно заполненную рамку логотипа. Правила пропорций SVG и пустые области внутри viewBox по-прежнему важны. Начните с одного выходного размера, если хотите исходные пропорции, затем проверьте результат.

Процентным размерам нужен родитель

Для копии образца, у которой корень использует width="50%" height="50%", этот вызов задает родительский контейнер 960 × 480 пикселей:

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

Наш результат был 480 × 240 пикселей: половина ширины родителя и половина его высоты. Это объясняет, почему parent_width=480 не взаимозаменяем с output_width=480.

Если CairoSVG сообщает, что размер SVG не определен, сначала проверьте корневые размеры. Задайте документу положительные размеры, подходящие для его использования, или родительские размеры, если проценты зависят от них. Не выводите нужный размер страницы из того, насколько крупно браузер случайно показывает изображение.

Физические размеры ведут себя иначе

Измените исходный корень на width="2.5in" height="1.25in", сохранив viewBox. В нашем тесте dpi=96 создал PNG 240 × 120, а dpi=192 — PNG 480 × 240. Оба PDF остались размером 180 × 90 пунктов.

Здесь исходник определяет физический размер, поэтому больше пикселей на дюйм увеличивает разрешение растра, сохраняя физический размер страницы PDF. Тот же принцип позволяет намеренно созданной странице использовать миллиметры или дюймы. Проверяйте рамку страницы экспортированного PDF вместо предположения, что большое количество пикселей означает страницу A4 или letter.

Если логотип должен размещаться внутри отчета с текстом, полями и несколькими элементами, используйте этап компоновки документа. Наше руководство по размещению SVG в ReportLab рассматривает прямое построение PDF; проверки ресурсов и размеров WeasyPrint — HTML-документы.

Проверьте экспорт, включая сохраненный вектор

Мы читали заголовки PNG через Pillow, а рамки страниц PDF и потоки содержимого через pypdf 6.10.0. Каждый из четырех PDF из пиксельного исходника содержал операции рисования контуров и ноль изображений страницы. Это подтверждает векторную геометрию для этого простого образца без изображений. Это не устанавливает полную точность для произвольного SVG.

Для проверки своих выходных размеров установите pillow и pypdf в той же среде и выполните:

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

Справка PageObject описывает mediabox и images. Количество изображений полезно для диагностики, но не доказывает правильное сохранение каждой фигуры, шрифта или эффекта.

Перед передачей:

1. Откройте PNG и PDF и сравните эмблему с SVG. Проверьте отверстие, треугольник, полоску и поля.
2. Независимо проверьте пиксельные размеры PNG и физические размеры PDF.
3. Проверьте изображение в нужном размере использования, включая узкие зазоры и мелкие детали.
4. Сохраните исходный SVG и повторите эти проверки после его изменения или обновления конвертера.

Страница поддержки SVG в CairoSVG говорит, что векторный вывод сохраняется, где возможно. Встроенные растровые изображения остаются растровым содержимым. Если файл содержит PNG в оболочке SVG, диагностика встроенного изображения поможет выявить его перед экспортом.

CairoSVG — статическое средство отрисовки. Анимация, скрипты, сложная компоновка текста и многие фильтры выходят за пределы его поддерживаемого процесса. Документация перечисляет как поддерживаемые фильтры только feOffset, feBlend и feFlood. Для графики, зависящей от других эффектов, внимательно сравните результат или экспортируйте через приложение, поддерживающее эти функции. Одного успешного вызова преобразования недостаточно.

Восстанавливайте векторный оригинал только при необходимости

Если логотип сохранился только в PNG или JPG, PerfectVector может выполнить предшествующий этап растра в SVG перед экспортом CairoSVG. Проверьте восстановленные фигуры, небольшие отверстия и фирменные надписи в редакторе; затем сохраните автономный оригинал SVG. Наш процесс векторизации логотипов объясняет эту проверку.

Существующий редактируемый SVG может сразу перейти к экспорту. Преобразование его в PNG и повторная трассировка отбросят полезную исходную геометрию. Фотографии могут оставаться растровыми, если это задуманное содержимое.

Для логотипа только в растре попробуйте свое изображение в PerfectVector, проверьте контуры и отверстия SVG, затем проверьте и пиксельные размеры, и физический размер страницы результатов CairoSVG.

Частые вопросы

Почему смена DPI оставляет PNG того же размера? Если корень SVG использует пиксельные размеры, смена DPI не обязательно меняет количество пикселей PNG. В этом примере SVG 240 на 120 пикселей сохранил этот размер при 192 DPI. Используйте output_width или scale, если нужно больше выходных пикселей.

Родительская ширина — то же самое, что выходная ширина? Нет. parent_width задает контейнер для вычисления процентных размеров. output_width запрашивает окончательную выходную ширину. В примере корневая ширина 50% при parent_width 960 вычислялась как 480 пикселей.

Всегда ли CairoSVG создает полностью векторный PDF? Нет. CairoSVG сохраняет векторный вывод, где возможно, но SVG может включать растровые изображения и неподдерживаемые функции. Проверяйте содержимое и внешний вид PDF вместо восприятия расширения файла как доказательства.

Источники

1. CairoSVG documentation — Описывает установку, API преобразования, управление размерами и ограничения отрисовки.
2. CairoSVG SVG 1.1 support — Объясняет сохранение вектора, встроенные изображения и неподдерживаемые функции.
3. pypdf PageObject reference — Описывает интерфейсы рамки страницы и изображений, используемые для проверки PDF.