Модуль image содержит функции для загрузки и сохранения изображений, а также для преобразования поверхностей в форматы, используемые другими пакетами.

Обратите внимание, что нет класса Image; изображение загружается как объект Surface. Класс Surface позволяет выполнять манипуляции (рисовать линии, устанавливать пиксели, захват областей и т. д.).

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

• BMP

• GIF (неанимированные)

• JPEG

• LBM (и PBM, PGM, PPM)

• PCX

• PNG

• PNM

• SVG (ограниченная поддержка, использует Nano SVG)

• TGA (несжатые)

• TIFF

• WEBP

• XPM

Сохранение изображений поддерживает только ограниченный набор форматов. Вы можете сохранить в следующих форматах.

• BMP

• JPEG

• PNG

• TGA

JPEG и JPG, а также TIF и TIFF относятся к одному и тому же формату файла

pygame.image.load()

загрузить новое изображение из файла (или объекта типа файл)

load(filename) -> Surface

load(fileobj, namehint="") -> Surface

Загружает изображение из файла. Вы можете передать имя файла, объект типа Python-файл или pathlib.Path.

Pygame автоматически определит тип изображения (например, GIF или растровый) и создаст новый объект Surface из данных. В некоторых случаях ему потребуется знать расширение файла (например, изображения GIF должны заканчиваться на ".gif"). Если вы передаете объект типа "сырой файл", вы также можете передать исходное имя файла в качестве аргумента namehint.

Возвращаемая поверхность будет содержать тот же формат цвета, цветовой ключ и альфа-прозрачность, что и загружаемый файл. Часто нужно будет вызвать pygame.Surface.convert() без аргументов, чтобы создать копию, которая будет отображаться на экране быстрее.

Для альфа-прозрачности, как в изображениях .png, используйте метод pygame.Surface.convert_alpha() после загрузки, чтобы изображение имело прозрачность по пикселям.

Pygame может не всегда поддерживать все форматы изображений. Как минимум, он будет поддерживать несжатые BMP. Если pygame.image.get_extended() возвращает True, вы, скорее всего, сможете загрузить большинство изображений (включая PNG, JPG и GIF).

Для совместимости используйте os.path.join().

eg. asurf = pygame.image.load(os.path.join('data', 'bla.png'))

pygame.image.save()

сохранить изображение в файл (или объект типа файл)

save(Surface, filename) -> None

save(Surface, fileobj, namehint="") -> None

Это позволит сохранить вашу поверхность в формате BMP, TGA, PNG, или JPEG изображения. Если расширение имени файла не распознается, по умолчанию используется TGA. Оба формата файлов TGA, и BMP создают несжатые файлы. Вы можете передать имя файла, pathlib.Path или объект типа Python-файл. Для объектов типа "сырой файл" изображение сохраняется в формате TGA, если не указано имя файла с распознаваемым расширением.

Примечание

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

Изменено в pygame 1.8: Сохранение файлов PNG и JPEG.

Изменено в pygame 2.0.0: Добавлен параметр namehint, чтобы сделать возможным сохранение форматов, отличных от TGA, в файл-подобный объект. Сохранение в файл-подобный объект с JPEG возможно.

pygame.image.get_sdl_image_version()

получить номер версии библиотеки SDL_Image

get_sdl_image_version(linked=True) -> None

get_sdl_image_version(linked=True) -> (major, minor, patch)

Если pygame скомпилирован с расширенными форматами изображений, эта функция вернет номер версии библиотеки SDL_Image в виде кортежа из 3 целых чисел (major, minor, patch). Если нет, то вернет None.

По умолчанию linked=True, функция вернёт версию библиотеки, к которой привязан pygame, а linked=False вернёт версию библиотеки, к которой скомпилирован pygame.

Новое в pygame 2.0.0.

Изменено в pygame 2.2.0: Добавлен ключевой аргумент linked и поведение по умолчанию изменено с возврата скомпилированной версии на возвращение связанной версии

pygame.image.get_extended()

проверить, поддерживаются ли расширенные форматы изображений

get_extended() -> bool

Если pygame скомпилирован с расширенными форматами изображений, эта функция вернёт True. Определять, какие форматы будут доступны, всё ещё нельзя, но в целом вы сможете загрузить все.

pygame.image.tostring()

преобразование изображения в буфер байтов

tostring(Surface, format, flipped=False) -> bytes

Создаёт строку байтов, которая может быть передана с помощью методов fromstring или frombytes в других пакетах обработки изображений Python. Некоторые пакеты обработки изображений Python предпочитают изображения в формате «снизу вверх» (например, PyOpenGL). Если вы передадите True для аргумента flipped, буфер байтов будет вертикально перевёрнут.

Аргумент format — это строка одного из следующих значений. Обратите внимание, что только поверхности с 8 битами могут использовать формат "P". Другие форматы будут работать для любой поверхности. Также обратите внимание, что другие пакеты обработки изображений Python поддерживают больше форматов, чем pygame.

• P, 8-битные палитровые поверхности

• RGB, 24-битное изображение

• RGBX, 32-битное изображение с неиспользуемым пространством

• RGBA, 32-битное изображение с альфа-каналом

• ARGB, 32-битное изображение с альфа-каналом, стоящим первым

• BGRA, 32-битное изображение с альфа-каналом, с переставленными местами красным и синим каналами

• RGBA_PREMULT, 32-битное изображение с цветами, масштабированными на альфа-канал

• ARGB_PREMULT, 32-битное изображение с цветами, масштабированными на альфа-канал, альфа-канал стоит первым

Примечание

Предпочтительно использовать tobytes() начиная с pygame 2.1.3

Новое в pygame 2.1.3: Формат BGRA

pygame.image.tobytes()

передача изображения в буфер байтов

tobytes(Surface, format, flipped=False) -> bytes

Создаёт строку байтов, которую можно передать с помощью методов fromstring или frombytes в других пакетах обработки изображений Python. Некоторые пакеты Python предпочитают изображения в формате «снизу вверх» (например, PyOpenGL). Если вы передадите True в аргумент flipped, буфер байтов будет вертикально перевернут.

Аргумент format — строка с одним из следующих значений. Обратите внимание, что только 8-битные изображения могут использовать формат "P". Другие форматы будут работать с любыми изображениями. Также обратите внимание, что другие пакеты Python поддерживают больше форматов, чем pygame.

• P, 8-битные палитрированные изображения

• RGB, 24-битное изображение

• RGBX, 32-битное изображение со свободным пространством

• RGBA, 32-битное изображение с альфа-каналом

• ARGB, 32-битное изображение с альфа-каналом в начале

• BGRA, 32-битное изображение с альфа-каналом, с переставленными красным и синим каналами

• RGBA_PREMULT, 32-битное изображение с цветами, масштабированными по альфа-каналу

• ARGB_PREMULT, 32-битное изображение с цветами, масштабированными по альфа-каналу, альфа-канал в начале

Примечание

эта функция является псевдонимом для tostring(). Использование этой функции рекомендуется вместо tostring() начиная с pygame 2.1.3. Эта функция была введена, чтобы соответствовать другим библиотекам (PIL, numpy и т.д.), а также ожиданиям пользователей.

Новая в pygame 2.1.3.

pygame.image.fromstring()

создание нового изображения из буфера байтов

fromstring(bytes, size, format, flipped=False) -> Surface

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

Переданные байты и формат должны точно соответствовать заданному размеру изображения. В противном случае будет вызвано ValueError.

См. метод pygame.image.frombuffer() для потенциально более быстрого способа передачи изображений в pygame.

Примечание

предпочтительно использовать frombytes() начиная с pygame 2.1.3.

pygame.image.frombytes()

создание нового изображения из буфера байтов

frombytes(bytes, size, format, flipped=False) -> Surface

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

Переданные байты и формат должны точно соответствовать заданному размеру изображения. В противном случае будет вызвано ValueError.

См. метод pygame.image.frombuffer() для потенциально более быстрого способа передачи изображений в pygame.

Примечание

эта функция является псевдонимом для fromstring(). Использование этой функции рекомендуется вместо fromstring() начиная с pygame 2.1.3. Эта функция была введена, чтобы соответствовать другим библиотекам (PIL, numpy и т.д.), а также ожиданиям пользователей.

Новая в pygame 2.1.3.

pygame.image.frombuffer()

создание нового изображения, которое разделяет данные внутри буфера байтов

frombuffer(buffer, size, format) -> Surface

Создаёт новое изображение, которое напрямую разделяет данные пикселей из буфера. Этот буфер может быть типа bytes, bytearray, memoryview, pygame.BufferProxy или любым объектом, поддерживающим протокол буфера. Этот метод принимает аргументы, похожие на pygame.image.fromstring(), но не может вертикально перевернуть исходные данные.

Это будет работать значительно быстрее, чем pygame.image.fromstring(), так как данные пикселей не нужно выделять и копировать.

Он принимает следующие аргументы формата:

• P, 8-битные палитрированные изображения

• RGB, 24-битное изображение

• BGR, 24-битное изображение, с переставленными красным и синим каналами.

• RGBX, 32-битное изображение со свободным пространством

• RGBA, 32-битное изображение с альфа-каналом

• ARGB, 32-битное изображение с альфа-каналом в начале

• BGRA, 32-битное изображение с альфа-каналом, с переставленными красным и синим каналами

Новая в pygame 2.1.3: формат BGRA

pygame.image.load_basic()

загрузка нового изображения BMP из файла (или объекта файла)

load_basic(file) -> Surface

Загружает изображение из файла. Вы можете передать имя файла или объект файла Python, или объект pathlib.Path.

Эта функция поддерживает только загрузку «базового» формата изображения, то есть BMP формат. Эта функция всегда доступна, независимо от того, как был скомпилирован pygame.

pygame.image.load_extended()

загрузка изображения из файла (или объекта файла)

load_extended(filename) -> Surface

load_extended(fileobj, namehint="") -> Surface

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

Изменено в pygame 2.0.1: Эта функция всегда доступна, но вызывает NotImplementedError если расширенная поддержка форматов изображений не поддерживается. Ранее эта функция могла быть или не быть доступной в зависимости от состояния расширенной поддержки форматов изображений.

pygame.image.save_extended()

сохранение изображения png/jpg в файл (или объект файла)

save_extended(Surface, filename) -> None

save_extended(Surface, fileobj, namehint="") -> None

Это сохранит ваше изображение в формате PNG или JPEG.

В случае сохранения изображения в объект файла, эта функция использует аргумент namehint для определения формата сохраняемого файла. Сохраняет в JPEG в случае, если аргумент namehint не был указан при сохранении в объект файла.

Изменено в pygame 2.0.1: Эта функция всегда доступна, но вызывает NotImplementedError если расширенная поддержка форматов изображений не поддерживается. Ранее эта функция могла быть или не быть доступной в зависимости от состояния расширенной поддержки форматов изображений.