> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

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

> Преобразуйте SVG через CairoSVG, выберите ширину или масштаб, разберитесь с DPI и родительскими размерами, проверьте пиксели PNG и размер страницы PDF перед передачей.

Source: https://perfectvector.com/ru/blog/cairosvg-output-size

Language: ru
Author: Irene Kim
Published: 2026-09-22T08:00:00+09:00
Updated: 2026-09-29T08:00:00+09:00

Используйте `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. Установите конвертер закрепленной версии в среде проекта:

```bash
python -m pip install "CairoSVG==2.9.1"
```

CairoSVG также нужна нативная библиотека Cairo. Если установка или импорт не работают, следуйте примечаниям для вашей операционной системы в [документации по установке](https://cairosvg.org/documentation/#installation).

Сохраните эту исходную эмблему из трех контуров как `emblem.svg`. Квадратное отверстие помогает заметить отсутствующее правило заливки, а узкая полоска дает контрольную точку для мелких деталей. Это демонстрационная графика, созданная вручную, а не преобразование PerfectVector.

```xml
<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`:

```python
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.

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

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

[Справка CairoSVG по API и командной строке](https://cairosvg.org/documentation/#python) описывает входные имена файлов через `url`, байты SVG через `bytestring` и вывод в файл через `write_to`. В CLI расширение имени выходного файла выбирает формат.

![Иллюстрация одной геометрической эмблемы, разветвляющейся в два пропорционально похожих результата экспорта на холстах разного размера](https://perfectvector.com/blog/cairosvg-output-size/output-sizing.webp)

*Иллюстрация решения при экспорте: сохраните векторный оригинал, затем выберите размеры для каждой передачи. Измеренные результаты CairoSVG приведены ниже.*

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

Параметры с похожими названиями отвечают на разные вопросы. [Справка CairoSVG по размерам](https://cairosvg.org/documentation/#command-line) отделяет родительский контейнер от запрошенных выходных размеров.

| Ваше требование                                              | Параметр Python                 | Параметр CLI          | Что проверить                                           |
| ------------------------------------------------------------ | ------------------------------- | --------------------- | ------------------------------------------------------- |
| Создать PNG шириной ровно 480 пикселей                       | `output_width=480`              | `--output-width 480`  | Высоту и пропорции изображения                          |
| Удвоить вычисленные выходные размеры                         | `scale=2`                       | `--scale 2`           | Удвоение обоих размеров                                 |
| Вычислить корневую ширину или высоту, выраженную в процентах | `parent_width`, `parent_height` | `--width`, `--height` | Процент от заданного контейнера                         |
| Интерпретировать физические единицы, например дюймы          | `dpi`                           | `--dpi`               | Отдельно пиксельные размеры PNG и физический размер PDF |

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

| Настройки          | Размеры PNG  | Размеры страницы PDF |
| ------------------ | ------------ | -------------------- |
| По умолчанию       | 240 × 120 px | 180 × 90 pt          |
| `output_width=480` | 480 × 240 px | 360 × 180 pt         |
| `scale=2`          | 480 × 240 px | 360 × 180 pt         |
| `dpi=192`          | 240 × 120 px | 90 × 45 pt           |

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

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

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

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

```python
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](https://perfectvector.com/ru/blog/reportlab-svg) рассматривает прямое построение PDF; [проверки ресурсов и размеров WeasyPrint](https://perfectvector.com/ru/blog/weasyprint-svg-image-pdf) — HTML-документы.

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

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

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

```python
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`](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) описывает `mediabox` и `images`. Количество изображений полезно для диагностики, но не доказывает правильное сохранение каждой фигуры, шрифта или эффекта.

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

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

[Страница поддержки SVG в CairoSVG](https://cairosvg.org/svg_support/) говорит, что векторный вывод сохраняется, где возможно. Встроенные растровые изображения остаются растровым содержимым. Если файл содержит PNG в оболочке SVG, [диагностика встроенного изображения](https://perfectvector.com/ru/blog/svg-contains-raster-image) поможет выявить его перед экспортом.

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

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

Если логотип сохранился только в PNG или JPG, PerfectVector может выполнить предшествующий этап растра в SVG перед экспортом CairoSVG. Проверьте восстановленные фигуры, небольшие отверстия и фирменные надписи в редакторе; затем сохраните автономный оригинал SVG. Наш [процесс векторизации логотипов](https://perfectvector.com/ru/blog/how-to-vectorize-a-logo) объясняет эту проверку.

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

Для логотипа только в растре [попробуйте свое изображение в PerfectVector](https://perfectvector.com/ru/vectorize-logo), проверьте контуры и отверстия 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](https://cairosvg.org/documentation/) — Описывает установку, API преобразования, управление размерами и ограничения отрисовки.
2. [CairoSVG SVG 1.1 support](https://cairosvg.org/svg_support/) — Объясняет сохранение вектора, встроенные изображения и неподдерживаемые функции.
3. [pypdf PageObject reference](https://pypdf.readthedocs.io/en/stable/modules/PageObject.html) — Описывает интерфейсы рамки страницы и изображений, используемые для проверки PDF.

## Explore

- [Read the HTML article](https://perfectvector.com/ru/blog/cairosvg-output-size)
- [SVG в fpdf2: сохраните контуры в PDF на Python](https://perfectvector.com/ru/blog/fpdf2-svg-image.md)
- [SVG в PDFKit: векторный логотип без растеризации](https://perfectvector.com/ru/blog/pdfkit-svg.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
