Класс UImage: загрузка изображения из файла

Загрузить изображение из файла позволяет статический метод load(). Формат метода:

UImage.load(<Путь>)

В качестве параметра указывается путь к файлу. Если загрузка выполнена успешно,  то метод вернет объект UImage, а в противном случае — значение None. Пример:

from unicross_image.uimage import UImage

img = UImage.load("foto.png")
if img:
    print(img)  # UImage(width=500, height=333)
else:
    print("Не удалось загрузить изображение")

Без сторонних библиотек метод load() может загрузить файлы в следующих форматах:

• .uimage — собственный формат файла изображения библиотеки UImage. Если изображение содержит 4 канала, то оно загружается как есть с максимальной скоростью. Если изображение содержит один или три канала, то выполняется преобразование в формат RGBA (альфа-канал станет полностью непрозрачным);
• .ppm — бинарный формат (P6) файла PPM. Выполняется преобразование в формат RGBA. Альфа-канал станет полностью непрозрачным.

Если загружаемый файл имеет расширение .uimage, то методы load() и load_im() автоматически передают управление статическому методу load_uimage(). Этот метод можно вызывать непосредственно. Формат метода:

UImage.load_uimage(<Путь>)

В качестве параметра указывается путь к файлу с расширением .uimage. Если загрузка выполнена успешно, то метод вернет объект UImage, а в противном случае — значение None. Если изображение содержит 4 канала, то оно загружается как есть с максимальной скоростью. Если изображение содержит один или три канала, то выполняется преобразование в формат RGBA (альфа-канал станет полностью непрозрачным). Пример:

img = UImage.load_uimage("foto.uimage")
print(img) # UImage(width=500, height=333)

Если нужно загрузить изображения без преобразования, то следует воспользоваться статическим методом load_uimage_any(). Формат метода:

UImage.load_uimage_any(<Путь>)

В качестве параметра указывается путь к файлу с расширением .uimage. Если загрузка выполнена успешно, то метод вернет объект UImage, UImageRGB или UImageGray в зависимости от типа изображения, а в противном случае — значение None. Изображение загружается как есть с максимальной скоростью. Пример:

img = UImage.load_uimage_any("foto.uimage")
print(img)  # UImage(width=500, height=333)
img2 = UImage.load_uimage_any("foto2.uimage")
print(img2) # UImageRGB(width=500, height=333)
img3 = UImage.load_uimage_any("foto3.uimage")
print(img3) # UImageGray(width=500, height=333)

Если загружаемый файл имеет расширение .ppm, то методы load() и load_im() автоматически передают управление статическому методу load_ppm_p6(). Этот метод можно вызывать непосредственно для загрузки бинарного формата (P6) файла PPM. Формат метода:

UImage.load_ppm_p6(<Путь>)

В качестве параметра указывается путь к файлу с расширением .ppm. Если загрузка выполнена успешно, то метод вернет объект UImage, а в противном случае — значение None. При этом выполняется преобразование в формат RGBA (альфа-канал будет полностью непрозрачным). Пример:

img = UImage.load_ppm_p6("foto.ppm")
print(img) # UImage(width=500, height=333)

Загрузка изображения с помощью PIL (PILLOW)

Если доступна библиотека PIL (PILLOW), то с помощью метода load() можно загрузить изображения в форматах PNG, GIF, JPEG, BMP, TIFF и др. Полный список форматов доступен по ссылке:

https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html

Для сохранения альфа-канала следует использовать формат PNG. Если изображение не содержит альфа-канала, то выполняется преобразование.

Установить библиотеку PIL (PILLOW) можно с помощью команды:

pip install Pillow

Загрузка изображения с помощью ImageMagick

Если библиотека PIL (PILLOW) недоступна, то метод load() пытается загрузить изображение тех же самых форматов с помощью библиотеки ImageMagick. Поиск библиотеки ImageMagick выполняется в следующем порядке:

• проверка наличия каталога ImageMagick на одном уровне с каталогом unicross_image библиотеки UImage. Внутри каталога ImageMagick должен быть файл magick.exe;
• проверка наличия каталога ImageMagick в корне диска C:. Внутри каталога должен быть файл magick.exe;
• проверка наличия каталога ImageMagick в корне диска D:. Внутри каталога должен быть файл magick.exe;
• проверка наличия файла magick.exe в пути, прописанном в переменной окружения MAGICK_HOME.

Этот список просматривается сверху вниз. Поиск прекращается при первом успешном поиске. Увидеть найденный путь позволяет метод get_image_magick_path() объекта изображения:

img = UImage(1, 1)
print(img.get_image_magick_path())
# C:\ImageMagick\magick.exe

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

• каталог unicross_image с файлами библиотеки UImage должен быть доступен для записи и чтения без прав администратора. Кроме того, в пути не должно быть русских букв. Еще раз. Нельзя размещать библиотеку в системных папках и в папках с русским буквами в пути;
• в пути к файлу magick.exe не должно быть русских букв.

Получить путь к каталогу для временных файлов позволяет метод get_tmp_path(). Пример:

img = UImage(1, 1)
print(img.get_tmp_path())
# D:\UImage\unicross_image\tmp

Загрузить архив с библиотекой ImageMagick можно со страницы:

https://imagemagick.org/script/download.php

Для Windows x64 загрузить можно такой архив:

ImageMagick-7.1.2-8-portable-Q16-x64.7z

Версия библиотеки, используемая мной при тестировании:

C:\Users\Unicross>C:\ImageMagick\magick -version
Version: ImageMagick 7.0.11-13 Q16 x64 2021-05-17 https://imagemagick.org
Copyright: (C) 1999-2021 ImageMagick Studio LLC
License: https://imagemagick.org/script/license.php
Visual C++: 192829914
Features: Cipher DPC OpenCL
Delegates (built-in): bzlib cairo flif freetype gslib heic jng jp2 jpeg
 jxl lcms lqr lzma openexr pangocairo png ps raw rsvg tiff webp xml
 zip zlib

Если библиотека PIL (PILLOW) недоступна, то метод load() автоматически передает управлению методу load_im(), который пытается загрузить файл с помощью библиотеки ImageMagick. Этот метод можно вызывать непосредственно, особенно, если нужно загрузить файл в формате, который не поддерживает библиотека PIL. Формат метода:

UImage.load_im(<Путь>)

В качестве параметра указывается путь к файлу. Если загрузка выполнена успешно,  то метод вернет объект UImage, а в противном случае — значение None. Для сохранения альфа-канала следует использовать формат PNG. Если изображение не содержит альфа-канала, то выполняется преобразование в формат RGBA.

Если загружаемый файл имеет расширение .uimage, то метод load_im() автоматически передаст управление статическому методу load_uimage(). Если загружаемый файл имеет расширение .ppm, то метод load_im() автоматически передаст управление статическому методу load_ppm_p6().

Пример загрузки изображения только с помощью библиотеки ImageMagick:

from unicross_image.uimage import UImage

img = UImage.load_im("foto.png")
if img:
    print(img)  # UImage(width=500, height=333)
else:
    print("Не удалось загрузить изображение")

Загрузка изображение из файла в формате RAW RGBA

Для взаимодействия с библиотекой ImageMagick имеется статический метод load_rgba(), позволяющий загрузить изображение из файла в формате RAW RGBA. Этот формат хорошо понимает библиотека ImageMagick. Формат метода:

UImage.load_rgba(<Ширина>, <Высота>, <Путь>)

Формат RAW RGBA ничего не знает ни о ширине изображения, ни о его высоте. Он содержит только набор байтов в формате RGBA. Поэтому в первых двух параметрах нужно явно задать размеры изображения. В третьем параметре указывается путь до файла с расширением .rgba. Если загрузка выполнена успешно,  то метод вернет объект UImage, а в противном случае — значение None. Пример:

from unicross_image.uimage import UImage

img = UImage.load("foto.png")
if img:
    # Сохранение в формате RAW RGBA
    img.save_rgba("foto.rgba")
    
    # Размеры нужно хранить отдельно
    w, h = img.get_size()
    
    # Загрузка из файла в формате RAW RGBA
    img2 = UImage.load_rgba(w, h, "foto.rgba")
    if img2:
        print(img2)  # UImage(width=500, height=333)
    else:
        print("Не удалось загрузить изображение")
else:
    print("Не удалось загрузить изображение")

Класс входит в состав графической библиотеки UImage для Python 3. Описание библиотеки UImage