Работа с изображениями

Это руководство показывает, как рисовать картинки на холсте с помощью функции image(). Оно использует простой язык и много примеров, чтобы старшеклассники, для которых английский не является родным языком, могли понять каждый шаг.

Краткий обзор сигнатуры функции

from drawzero import *

image(image, pos, width: int = None, alpha=255)

Все примеры ниже используют такой же импорт, поэтому image() сразу доступна без дополнительных шагов.

Четыре параметра управляют тем, какой файл загружается, где он появляется, какой ширины становится и насколько прозрачным выглядит.

Параметр	Что это значит	Обязательный?	Типичные значения
`image`	Путь к файлу изображения (например, `'cat.png'` или `this_file_dir / 'cat.png'`)	Да	PNG, JPG или другие форматы, которые может открыть `pygame`
`pos`	Верхний левый угол, где будет нарисовано изображение на холсте	Да	Кортежи `(x, y)`, такие как `(100, 200)`
`width`	Желаемая ширина на холсте. Высота изменяется автоматически, чтобы сохранить пропорции.	Нет	Целые числа, такие как `200` или `350`
`alpha`	Прозрачность. `255` — полностью непрозрачный, `0` — невидимый.	Нет	Числа от `0` до `255`

ℹ️ Если вы хотите более глубокое объяснение прозрачности, прочтите Прозрачность (alpha) и толщина линии (line_width).

Параметр за параметром

`image`: выберите файл для рисования

Принимает строки с именами файлов, абсолютные пути или объекты pathlib.Path.
Относительные пути разрешаются относительно файла Python, который вызывает image(). Безопасный шаблон:
```
from pathlib import Path
this_file_dir = Path(__file__).resolve().parent
image(this_file_dir / 'pictures' / 'cat.png', (100, 100))
```
Изображения PNG сохраняют свой прозрачный фон. Файлы JPG игнорируют прозрачные пиксели, потому что формат их не хранит.
Большие изображения — это нормально, но очень большие файлы замедляют загрузку. Для игр или анимаций, по возможности, держите изображения размером до 2000×2000 пикселей.

Частые ошибки

Ввод неверного имени папки. Исправьте это, распечатав полный путь и проверив, существует ли файл.
Забыли расширение файла (.png, .jpg, .gif).
Использование обратных слэшей (\) в Windows внутри обычных строк. Либо используйте сырые строки (r'images\cat.png'), либо прямые слэши ('images/cat.png').

`pos`: разместите изображение на холсте

Холст использует ту же виртуальную систему координат 1000×1000, что и примитивы фигур.
(0, 0) — это верхний левый угол. Увеличение x перемещает изображение вправо. Увеличение y перемещает его вниз.
pos может быть кортежем, списком или объектом Pt.
Координаты представляют верхний левый угол изображения. Если вы хотите центрировать изображение, вычтите половину его ширины и высоты:
```
image('badge.png', (500 - 128, 500 - 128))
```
image() округлит числа до ближайшего пикселя. Десятичные дроби разрешены, но внутренне они преобразуются в целые числа.

`width`: управляйте размером, не нарушая пропорций

Оставьте его как None, чтобы сохранить исходный размер файла.
Передайте положительное целое число, чтобы масштабировать изображение по горизонтали. Помощник автоматически вычисляет соответствующую высоту, чтобы изображение не выглядело растянутым.
Значение измеряется в виртуальных единицах холста. При окне по умолчанию 1000×1000 width=200 показывает изображение шириной 200 пикселей.
Установите width на одно и то же значение для всех кадров в анимации, чтобы избежать мерцания.
Вы можете вычислять ширину динамически. Например, для масштабирования на 50%:
```
original_width = 400
image('robot.png', (300, 400), width=original_width // 2)
```
Передача 0 или отрицательного значения вызовет BadDrawParmsError. Всегда используйте положительное целое число.

`alpha`: смешивайте изображения с фоном

Принимает целые числа от 0 (полностью прозрачный) до 255 (полностью непрозрачный).
Значение по умолчанию 255 рисует изображение без дополнительной прозрачности.
Используйте значения среднего диапазона (например, 128) для создания мягких теней, эффектов стекла или намеков на движение.
Значение альфа-канала применяется ко всему изображению. Прозрачность попиксельно, хранящаяся в файлах PNG, по-прежнему работает и умножается на это значение.
Прочтите полное руководство по прозрачности, чтобы увидеть примеры наслоения и советы по смешиванию.

Пошаговые примеры

Пример 1 – показать талисман в углу

from drawzero import *

fill('white')
image('mascot.png', (50, 50))

Талисман сохраняет свой первоначальный размер. Белый фон делает цвета хорошо видимыми.

Пример 2 – центрировать изображение и масштабировать его до фиксированной ширины

from drawzero import *
from pathlib import Path

this_file_dir = Path(__file__).resolve().parent
logo_path = this_file_dir / 'assets' / 'school_logo.png'

# Нарисовать логотип шириной 300 единиц и сохранить его по центру холста
logo_width = 300
logo_x = 500 - logo_width // 2
logo_y = 300
image(logo_path, (logo_x, logo_y), width=logo_width)

Этот фрагмент работает, даже если вы переместите скрипт на другой компьютер, потому что путь строится относительно местоположения файла.

Пример 3 – призрачный след с использованием альфа-канала

from drawzero import *

fill('black')
for step in range(5):
    image('spaceship.png', (150 + step * 80, 400), width=200, alpha=255 - step * 40)

Цикл рисует пять копий одного и того же изображения. Каждая копия более прозрачна, чем предыдущая, создавая след движения.

Пример 4 – адаптивная ширина в зависимости от размера окна

from drawzero import *

fill((10, 10, 40))
window_width = 800  # представим, что мы измерили реальное окно
picture_width = int(window_width * 0.6)
image('city.png', (100, 200), width=picture_width)

Поскольку ширина вычисляется в коде, вы можете адаптировать ее к разным размерам экрана.

Контрольный список перед вызовом `image()`

Поместите файл с изображением в папку проекта (например, docs/ или assets/).
Убедитесь, что скрипт Python может получить доступ к пути к файлу (распечатайте его при необходимости).
Определите координаты размещения. Используйте grid() из DrawZero, если вам нужна помощь в визуализации позиций.
Выберите ширину или оставьте ее как None.
Решите, нужна ли вам дополнительная прозрачность.
Только после этого вызывайте image().

Руководство по устранению неполадок

Проблема	Вероятная причина	Как исправить
`BadDrawParmsError: bad coords`	Аргумент `pos` не является кортежем или списком из двух чисел.	Убедитесь, что вы передаете `(x, y)` с числами.
`No file '...' found in working directory`	Неверный путь к изображению.	Распечатайте `Path(image).resolve()` и убедитесь, что файл существует.
Изображение выглядит растянутым	Вы установили и `width`, и `height`. Следует указывать только `width`.	Удалите любое ручное масштабирование высоты. DrawZero вычисляет ее за вас.
Изображение очень размытое	Вы масштабировали крошечное изображение до огромного размера.	Начните с файла с более высоким разрешением или уменьшите целевую ширину.
Прозрачный PNG выглядит слишком сплошным	Вы использовали `alpha=255`.	Уменьшите значение альфа-канала, чтобы фон просвечивал.

С этими советами вы сможете уверенно отображать изображения и комбинировать их с примитивами рисования.