UImageCV: библиотека компьютерного зрения для Python, C и C++

Библиотека UImageCV для Python 3.8+ (только для Windows) содержит алгоритмы компьютерного зрения. Она является надстройкой над библиотекой UImageC (пакет unicross_img), которая позволяет загрузить, сохранить и обработать изображение. В свою очередь библиотека UImageC является надстройкой над библиотеками Pillow и ImageMagick. При этом базовый функционал библиотеки реализован на языке C.

Для тесного взаимодействия с библиотекой OpenCV имеется класс UImageBGR. Массивы ctypes, используемые классом UImageBGR, можно обернуть в массивы NumPy, используемые библиотекой OpenCV, без копирования данных:

from unicross_cv.uimagebgr import UImageBGR
from unicross_img.uhelper_np import UHelperNP
import cv2

img = UImageBGR.load("foto.jpg")
print(img)           # UImageBGR(width=500, height=333)
# Преобразование в массив NumPy без копирования
np_gray = cv2.cvtColor(img.get_buffer(), cv2.COLOR_BGR2GRAY)
print(type(np_gray)) # <class 'numpy.ndarray'>
print(np_gray.shape) # (333, 500)
# Преобразование массива NumPy в UImageGray
img_gray = UHelperNP.ndimage_to_uimage(np_gray)
print(img_gray)      # UImageGray(width=500, height=333)

Большинство алгоритмов в библиотеке UImageCV реализованы на языке C и не зависят от библиотеки OpenCV или любой другой библиотеки компьютерного зрения. Поэтому предыдущий пример можно записать проще и без всяких лишних преобразований в BGR:

from unicross_img.uimagergb import UImageRGB

img = UImageRGB.load("foto.jpg")
print(img)           # UImageRGB(width=500, height=333)
# Преобразование в UImageGray
img_gray = img.get_uimagegray()
print(img_gray)      # UImageGray(width=500, height=333)

Благодаря использованию массивов ctypes, которые доступны напрямую через атрибут arr, имеется возможность непосредственной обработки изображения с помощью компилируемых языков C, C++, Go и др. с максимальной скоростью без копирования. Переделаем предыдущий пример и используем C API напрямую:

from unicross_img.uimagergb import UImageRGB
from unicross_img.uimagegray import UImageGray
import os.path
import ctypes

# Использование UImage C API
dll_path = r"D:\UImageC\unicross_img\bin"
_ulibpath = os.path.abspath(os.path.join(dll_path, "libuimagergb.dll"))
_ulibc = ctypes.CDLL(_ulibpath)

_uimagergb_to_gray = _ulibc.uimagergb_to_gray
_uimagergb_to_gray.argtypes = [
   ctypes.POINTER(ctypes.c_ubyte), ctypes.c_int,
   ctypes.POINTER(ctypes.c_ubyte), ctypes.c_int]
_uimagergb_to_gray.restype = ctypes.c_int

img = UImageRGB.load("foto.jpg")
print(img)           # UImageRGB(width=500, height=333)
# Преобразование в UImageGray. Подготовка буфера
img_gray = UImageGray(img.get_width(), img.get_height())
# Вызываем код на языке C (arr не копируется!)
res = _uimagergb_to_gray(img.arr, img.arr._length_,
                         img_gray.arr, img_gray.arr._length_)
if res == 1:
    print(img_gray)  # UImageGray(width=500, height=333)
    img_gray.save("test.png")
else:
    print("Ошибка при выполнении операции")

Библиотека компьютерного зрения UImageCV помимо кода на Python содержит также код на языке C, который можно вызвать из программ на Python, C или C++. Код компилируется в динамические библиотеки (dll) под Windows x64. Подключить библиотеку в программе на Python позволяет модуль ctypes, входящий в состав стандартной библиотеки. В предыдущем примере мы использовали код на языке C, расположенный в libuimagergb.dll. Точно также можно подключить любую другую динамическую библиотеку и выполнять обработку изображения на компилируемых языках.

Динамические библиотеки, входящие в состав UImageCV C API, не имеют зависимостей от кода сторонних библиотек! Все названия функций внутри dll находятся в своих собственных пространствах имен (в коде выше это префикс "uimagergb_" перед названием функции), поэтому конфликтов имен с кодом сторонних разработчиков быть не должно!

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

Системные требования и ограничения

Для корректной работы библиотеки нужно соблюсти следующие условия:

• операционная система Windows 8, 8.1, 10 или 11. Разрядность x64;
• процессор чем мощнее, тем лучше;
• наличие библиотеки Python 3.8+;
• для использования всех возможностей требуются библиотеки Pillow, ImageMagick, OpenCV, NumPy и Matplotlib. При отсутствии какой-либо библиотеки некоторые возможности станут недоступны;
• минимум 1 ГБайт свободного места в оперативной памяти;
• минимум 100 МБайт свободного места на жестком диске.

Библиотека имеет следующие основные ограничения:

• максимальная ширина изображения — 8000 px;
• максимальная высота изображения — 8000 px.

Библиотека работает только в Windows x64. Библиотеки Python, Pillow, ImageMagick, OpenCV, NumPy и Matplotlib в комплект не входят. Установка Python 3.8 под Windows подробно описана в документации (см. каталог docs\test_python\setup_python). Процесс установки Pillow, OpenCV, NumPy и Matplotlib предельно прост:

pip install Pillow
pip install opencv-python
pip install numpy
pip install matplotlib

Версии этих библиотек, использованные при тестировании:

>>> import PIL
>>> PIL.__version__
'9.3.0'
>>> import cv2
>>> cv2.__version__
'4.6.0'
>>> import numpy
>>> numpy.__version__
'1.23.4'
>>> import matplotlib
>>> matplotlib.__version__
'3.6.2'

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

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

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

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

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

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

Подключение библиотеки и импорт классов из модулей

Библиотека UImageCV включает два пакета:

• пакет unicross_img — содержит код библиотеки UImageC ;
• пакет unicross_cv — содержит  собственно код библиотеки UImageCV.

Оба пакета нужно разместить либо в одном пространстве имен в путях поиска модулей, либо просто рядом друг с другом. Если программа расположена рядом с каталогами библиотек, то подключение модуля из пакета и импорт класса выполняются примерно так:

from unicross_img.uimagergb import UImageRGB
from unicross_cv.uimagebgr import UImageBGR

Если программа расположена в другом месте, то предварительно нужно прописать путь к библиотекам в пути поиска модулей:

import sys
sys.path.append(r"D:\UImageC")
from unicross_img.uimagergb import UImageRGB
from unicross_cv.uimagebgr import UImageBGR

Проверим установку путем вывода версий библиотек:

import unicross_img
import unicross_cv

print(unicross_img.__version__) # 1.1.0
print(unicross_img.VERSION)     # ('1', '1', '0')
print(unicross_cv.__version__)  # 1.0.0
print(unicross_cv.VERSION)      # ('1', '0', '0')

Модули библиотеки UImageCV

Внутри пакета  unicross_cv расположены следующие модули:

• uimagebgr.py — содержит класс UImageBGR, предназначенный для хранения цветного изображения с 3-я каналами BGR (c_ubyte от 0 до 255);
• uimagebgrchange.py — содержит класс UImageBGRChange, предназначенный для выполнения преобразований UImageBGR (средствами Pillow или ImageMagick и без). Почти все методы принимают объект UImageBGR и возвращают копию преобразованного объекта UImageBGR или None;
• uimagedraw.py — модуль для рисования. Содержит следующие идентификаторы:

• класс UImageBGRDrawPIL, предназначенный для рисования на UImageBGR средствами Pillow;
• класс UImageBGRDrawCv2, предназначенный для рисования на UImageBGR средствами OpenCV;

• uimagehsv.py — содержит класс UImageHSV, предназначенный для хранения цветного изображения с 3-я каналами HSV (c_ubyte от 0 до 255);
• uimagehsl.py — содержит класс UImageHSL, предназначенный для хранения цветного изображения с 3-я каналами HSL (c_ubyte от 0 до 255). Преобразование цветовых моделей выполняется средствами OpenCV;
• uimagelab.py — содержит класс UImageLab, предназначенный для хранения цветного изображения с 3-я каналами Lab (c_ubyte от 0 до 255). Преобразование цветовых моделей выполняется средствами OpenCV;
• uhelper_cv2.py — вспомогательный модуль для взаимодействия с OpenCV. Содержит класс UHelperCv2 с помощью которого можно загрузить изображение из файла или сохранить изображение в файл;
• ucvbgr.py — содержит класс UCvBGR, предназначенный для выполнения алгоритмов компьютерного зрения с изображением UImageBGR. Преобразование цветовых моделей выполняется средствами OpenCV;
• ucvrgb.py — содержит класс UCvRGB, предназначенный для выполнения алгоритмов компьютерного зрения с изображением UImageRGB. Преобразование цветовых моделей выполняется средствами OpenCV;
• ucvgray.py — содержит класс UCvGray, предназначенный для выполнения алгоритмов компьютерного зрения с изображением UImageGray;
• ucvgrayfilter.py — содержит класс UCvGrayFilter, предназначенный для выполнения алгоритмов компьютерного зрения с изображением UImageGray (свертка, морфологические операции и др.);
• ucvgrayedges.py — содержит класс UCvGrayEdges, предназначенный для выполнения алгоритмов компьютерного зрения с изображением UImageGray (выделение границ объектов);
• ucvgrayblur.py — содержит класс UCvGrayBlur, предназначенный для выполнения алгоритмов компьютерного зрения с изображением UImageGray (размытие и усиление резкости).

Как заказать библиотеки UImageCV и UImageCV C API

Библиотеки не продаются. Библиотеки лицензируются одной из трех типов лицензий: User, Company или Public.

• Лицензия User — предоставляется на одного пользователя. Библиотека может использоваться только в личных целях. Любое распространение библиотеки запрещено. Лицензия User предоставляет неисключительную и непередаваемую лицензию, не предполагающую права предоставления какой-либо сублицензии, на использование библиотеки в течение срока действия лицензии. Срок действия лицензии не ограничен. Число единиц ПО, использующих библиотеку, не ограничено. Лицензия User доступна только физическим лицам. Стоимость лицензии на UImageCV — 5 000 руб., на UImageCV C API (только DLL) — 4 000 руб.
• Лицензия Company — предоставляется на одну фирму и одно наименование ПО. Программа с библиотекой может использоваться сотрудниками внутри фирмы. Использование программы с библиотекой клиентами фирмы возможно, но только удаленно, например, предоставление сервиса на сайте (с размещением библиотеки на сервере) без непосредственного доступа клиента к коду библиотеки. Любое распространение библиотеки и программы с библиотекой запрещено. Лицензия Company предоставляет неисключительную и непередаваемую лицензию, не предполагающую права предоставления какой-либо сублицензии, на использование библиотеки в течение срока действия лицензии. Срок действия лицензии не ограничен. Лицензия Company доступна только юридическим лицам.  Стоимость лицензии на UImageCV — 25 000 руб., на UImageCV C API (только DLL) — 20 000 руб.
• Лицензия Public — предоставляется на одно наименование ПО. Библиотека может использоваться только в составе ПО, распространяемого публично (платно или бесплатно). Учитывая, что исходные коды динамических библиотек (DLL), входящих в состав библиотеки, не предоставляются, запрещено использовать библиотеку в составе ПО, распространяемого по лицензии GPL и аналогичным, требующим обязательное публичное предоставление всех исходных кодов. Лицензия Public предоставляет неисключительную и непередаваемую лицензию, не предполагающую права предоставления какой-либо сублицензии, на использование библиотеки в течение срока действия лицензии. Срок действия лицензии не ограничен. Лицензия Public доступна физическим и юридическим лицам. Стоимость лицензии на UImageCV — 100 000 руб., на UImageCV C API (только DLL) — 80 000 руб.

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

Лицензия, выданная на библиотеку UImageCV (или UImageCV C API), распространяется и на библиотеку UImageC (или UImage C API), входящую в состав дистрибутива, при условии неделимого совместного использования библиотек. Если вы решили использовать библиотеку UImageC отдельно от UImageCV, то нужно приобрести отдельную лицензию на использование библиотеки UImageC.

Исходные коды динамических библиотек (DLL) не предоставляются и их распространение запрещено.

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

Документация содержится в строках документирования. Для получения списка методов нужно использовать функцию dir(), а для получения описания метода — функцию help(). Специализированные текстовые редакторы автоматически предоставят список методов при наборе букв и описание метода из строки документирования при выборе метода из списка. Расширенная документация по C API доступна только в руководстве разработчика, которое в состав библиотеки не входит и приобретается отдельно.

Чтобы иметь полное представление о возможностях библиотеки, нужно приобрести руководство разработчика в формате HTML. В его состав входит расширенная документация и множество примеров, которые можно запустить на выполнение и наглядно увидеть результат. Дополнительно доступны заголовочные файлы (с расширением .h), которые могут быть использованы исключительно в целях динамической линковки вашего ПО с DLL при сборке и компиляции на вашем компьютере. Распространение руководства разработчика и заголовочных файлов запрещено.

Доступны для заказа следующие руководства разработчика в формате HTML (можно открыть любым Web-браузером; оглавление в файле index.html):

• "UImageC и UImage C API. Руководство разработчика". Включает заголовочные файлы для UImage C API. Оглавление руководства. Стоимость 250 руб.
• "UImageCV и UImageCV C API. Руководство разработчика". Включает заголовочные файлы для  UImageCV C API. Оглавление руководства. Стоимость 300 руб.

Прежде чем заказывать библиотеку:

• прочтите текст Лицензии. Только если она вас полностью устраивает переходите к следующему шагу;
• выберите библиотеку и тип лицензии, подходящий под вашу программу или задачу. Учитывайте, что изменять что-либо в дистрибутиве библиотеки нельзя. Это означает, что просто скопировать  DLL в каталог bin вашей программы при заказе UImageC или UImageCV не получится. Нужно будет целиком копировать каталог с библиотекой или прописывать путь. Если библиотеку планируется использовать только в C или C++, то правильнее будет заказать UImage C API или UImageCV C API. В комплект этих библиотек входят только DLL и лицензия, которые можно скопировать в  каталог bin вашей программы;
• закажите соответствующее руководство разработчика, чтобы полностью понимать возможности выбранной библиотеки;
• закажите лицензию User, чтобы попробовать на практике и убедиться, что библиотека вам подходит. Вы всегда можете повысить лицензию до Company или Public с зачетом уже оплаченной суммы. В обратную сторону это не действует;
• закажите повышение лицензии с зачетом, если лицензия User вас не устраивает.

Если есть вопросы, то задавайте. Контакты и форма для заказа

Описание библиотеки UImageC