image — машинное зрение

Модуль image – это сердце стека машинного зрения OpenMV. Он предоставляет класс Image – находящийся в памяти буфер пикселей, с которым работают все процедуры рисования, фильтрации, преобразования и извлечения признаков, – вместе со вспомогательными объектами результатов, возвращаемыми этими процедурами (Blob, Line, Circle, Rect, QRCode, AprilTag, DataMatrix, BarCode, …), и вспомогательными классами, используемыми для их настройки (Threshold, Histogram, Statistics, HaarCascade, Similarity, Percentile, Displacement, ImageIO).

Получение изображения

Существует четыре способа поместить Image в оперативную память:

  • Живой захват с датчика камеры. Вызовите csi.CSI.snapshot(), чтобы захватить следующий кадр прямо в буфер кадра; возвращаемый объект Image ссылается на этот буфер.

  • Из файла. Передайте путь в конструктор Image (image.Image("/sd/photo.jpg")); поддерживаемые форматы на диске – это BMP, PPM/PGM, JPEG, PNG и формат записи OpenMV ImageIO.

  • Из ndarray. Передайте float32 (h, w) или (h, w, 3) ndarray в конструктор Image. Пиксели масштабируются из 0.0 -- 255.0 в изображение GRAYSCALE или RGB565 соответственно. Используйте это, чтобы вернуть тензорный вывод из ml (или любого конвейера ulab) обратно в изображение, пригодное для рисования.

  • Пустой буфер. Создайте Image с заданным размером и форматом пикселей (image.Image(320, 240, image.RGB565)), чтобы рисовать в нём с нуля или использовать как временную поверхность для арифметики над изображениями.

Форматы пикселей

Каждое Image имеет один из следующих форматов пикселей; выбор – это компромисс между памятью, стоимостью обработки и тем, какие алгоритмы могут на нём работать. Используйте BINARY, GRAYSCALE, RGB565, BAYER, YUV422, JPEG или PNG в качестве аргумента pixformat при создании изображения или настройке датчика камеры:

  • BINARY (1 bpp) – один бит на пиксель. Самый компактный формат; используется внутри процедур пороговой обработки и морфологии, но редко захватывается напрямую с датчика.

  • GRAYSCALE (8 bpp) – один байт на пиксель (канал Y из YUV422). Самый быстрый формат для большинства алгоритмов машинного зрения (AprilTag, обнаружение границ, оптический поток).

  • RGB565 (16 bpp) – два байта на пиксель, 5 бит красного / 6 бит зелёного / 5 бит синего. Цветовой формат по умолчанию.

  • BAYER (8 bpp) – необработанные цветные данные в виде шаблона Байера прямо с датчика. Полезно для собственного дебайеринга или для хранения большего числа пикселей в меньшем объёме памяти с последующим дебайерингом по запросу.

  • YUV422 (16 bpp) – цвет с цветностью, прореженной 4:2:2, два байта на пиксель. Полезно, когда нужны алгоритмы, специфичные для цветности, без полной стоимости RGB.

  • JPEG / PNG – сжатые буферы. Лучше всего подходят для хранения и передачи по сети. Операции на уровне пикселей сначала требуют Image.to_grayscale() или Image.to_rgb565().

Работа с результатами

Методы обнаружения / извлечения признаков класса Image возвращают объекты, которые можно перебирать и комбинировать: вызов Image.find_blobs() возвращает список Blob, вызов Image.find_apriltags() возвращает список AprilTag и так далее. Каждый класс результата предоставляет геометрические свойства обнаружения (центроид, ограничивающую рамку, площадь, значение кода и т. д.), так что вы можете действовать на их основе напрямую или передавать их обратно в методы рисования (Image.draw_rectangle(), Image.draw_string(), …).

Вспомогательные функции цветовых пространств

Модуль также предоставляет небольшие чистые функции для преобразования отдельных значений пикселей между цветовыми пространствами binary / grayscale / RGB / LAB / YUV. Они полезны, когда нужно преобразовать значения порога или элементы палитры в Python перед передачей их в операции над изображениями; для преобразования целого изображения используйте методы to_* класса Image, которые намного быстрее, чем вызов этих вспомогательных функций в цикле.

Классы

Функции

Вспомогательные функции преобразования цветовых пространств

Каждая из приведённых ниже функций X_to_Y выполняет одно преобразование значения пикселя. Все они принимают/возвращают значения в канонических диапазонах OpenMV:

  • binary – int 0 – 1.

  • grayscale – int 0 – 255.

  • RGB – кортеж (r, g, b) из 8-битных целых чисел (каждое 0 – 255).

  • LAB – кортеж (l, a, b), где L в диапазоне 0 – 100, а A/B в диапазоне -128 – 127.

  • YUV – кортеж (y, u, v), где Y в диапазоне 0 – 255, а U/V в диапазоне -128 – 127.

Для преобразования целого изображения используйте методы to_* класса Image, которые намного быстрее, чем вызов этих вспомогательных функций в цикле.

image.binary_to_grayscale(value: int) → int

Преобразует значение binary в значение grayscale.

image.binary_to_rgb(value: int) → Tuple[int, int, int]

Преобразует значение binary в кортеж RGB.

image.binary_to_lab(value: int) → Tuple[int, int, int]

Преобразует значение binary в кортеж LAB.

image.binary_to_yuv(value: int) → Tuple[int, int, int]

Преобразует значение binary в кортеж YUV.

image.grayscale_to_binary(value: int) → int

Преобразует значение grayscale в значение binary.

image.grayscale_to_rgb(value: int) → Tuple[int, int, int]

Преобразует значение grayscale в кортеж RGB.

image.grayscale_to_lab(value: int) → Tuple[int, int, int]

Преобразует значение grayscale в кортеж LAB.

image.grayscale_to_yuv(value: int) → Tuple[int, int, int]

Преобразует значение grayscale в кортеж YUV.

image.rgb_to_binary(value: Tuple[int, int, int]) → int

Преобразует кортеж RGB в значение binary.

image.rgb_to_grayscale(value: Tuple[int, int, int]) → int

Преобразует кортеж RGB в значение grayscale.

image.rgb_to_lab(value: Tuple[int, int, int]) → Tuple[int, int, int]

Преобразует кортеж RGB в кортеж LAB.

image.rgb_to_yuv(value: Tuple[int, int, int]) → Tuple[int, int, int]

Преобразует кортеж RGB в кортеж YUV.

image.lab_to_binary(value: Tuple[int, int, int]) → int

Преобразует кортеж LAB в значение binary.

image.lab_to_grayscale(value: Tuple[int, int, int]) → int

Преобразует кортеж LAB в значение grayscale.

image.lab_to_rgb(value: Tuple[int, int, int]) → Tuple[int, int, int]

Преобразует кортеж LAB в кортеж RGB.

image.lab_to_yuv(value: Tuple[int, int, int]) → Tuple[int, int, int]

Преобразует кортеж LAB в кортеж YUV.

image.yuv_to_binary(value: Tuple[int, int, int]) → int

Преобразует кортеж YUV в значение binary.

image.yuv_to_grayscale(value: Tuple[int, int, int]) → int

Преобразует кортеж YUV в значение grayscale.

image.yuv_to_rgb(value: Tuple[int, int, int]) → Tuple[int, int, int]

Преобразует кортеж YUV в кортеж RGB.

image.yuv_to_lab(value: Tuple[int, int, int]) → Tuple[int, int, int]

Преобразует кортеж YUV в кортеж LAB.

Дескрипторы признаков

image.HaarCascade(path: str, stages: int = -1) → Cascade

Загружает Haar Cascade и возвращает дескриптор Cascade для использования с Image.find_features().

path может быть одним из:

  • буквальной строкой "frontalface" или "eye" для загрузки одного из двух каскадов, встроенных в ROM прошивки, или

  • путём в файловой системе к пользовательскому двоичному файлу .cascade, созданному инструментами конвертера каскадов OpenMV.

stages выбирает, сколько стадий каскада оценивать во время обнаружения. -1 использует все стадии, хранящиеся в файле. Уменьшение этого значения ускоряет обнаружение ценой увеличения числа ложных срабатываний.

image.load_descriptor(path: str) → kp_desc | lbp_desc

Загружает дескриптор из файла по пути path и возвращает его. Внутренний тег типа файла определяет, какой класс дескриптора будет восстановлен:

image.save_descriptor(descriptor: kp_desc | lbp_desc, path: str) → None

Сериализует descriptor (дескриптор ключевых точек ORB или дескриптор LBP) в файл по пути path в формате файла дескриптора OpenMV. Этот же файл можно позже загрузить заново через image.load_descriptor().

image.match_descriptor(descriptor0, descriptor1, threshold: int = 85, filter_outliers: bool = False) → int | kptmatch

Сопоставляет два дескриптора одного типа.

  • Для двух дескрипторов LBP – возвращает целочисленное расстояние Хэмминга между ними (меньшее значение означает более близкое совпадение).

  • Для двух дескрипторов ключевых точек ORB – возвращает kptmatch, описывающий кластер сопоставленных ключевых точек, или None, если ни одно совпадение не проходит threshold.

threshold (0 – 100) задаёт, насколько строгим является сопоставление ORB при принятии пары ключевых точек. Меньшие значения ужесточают сопоставление, отклоняя слабые совпадения по ближайшему соседу.

filter_outliers включает отбраковку выбросов в стиле RANSAC по набору сопоставленных ключевых точек. Используйте это, когда ожидаете единое жёсткое преобразование между двумя видами; отключите, когда сопоставленные ключевые точки охватывают несколько объектов.

Вспомогательные функции геометрии блобов

Эти вспомогательные функции принимают Blob (как возвращается Image.find_blobs()) и вычисляют дополнительные геометрические свойства по запросу. Они находятся на уровне модуля – а не у Blob, – поэтому базовый путь find_blobs() не несёт затрат на них, пока вы их не запросите.

image.get_solidity(blob: blob) → float

Возвращает плотность (blob.pixels / convex_hull_area) блоба blob. Число с плавающей точкой, 0 – 1; 1.0 означает, что блоб полностью заполняет свою выпуклую оболочку.

image.get_convexity(blob: blob) → float

Возвращает выпуклость (convex_hull_perimeter / blob.perimeter) блоба blob. Число с плавающей точкой, 0 – 1; 1.0 – это идеально выпуклый блоб.

image.get_major_axis_line(blob: blob) → line

Возвращает Line вдоль большой оси блоба blob (более длинной из двух главных осей повёрнутого прямоугольника минимальной площади).

image.get_minor_axis_line(blob: blob) → line

Возвращает Line вдоль малой оси блоба blob (более короткой из двух главных осей повёрнутого прямоугольника минимальной площади).

image.get_enclosing_circle(blob: blob) → circle

Возвращает Circle, охватывающий блоб blob.

image.get_enclosed_ellipse(blob: blob) → Tuple[int, int, int, int, int]

Возвращает кортеж из 5 элементов (cx, cy, a, b, rotation), описывающий эллипс, вписанный в повёрнутый прямоугольник минимальной площади вокруг блоба blob:

  • cx / cy – центр эллипса в пикселях (целое число).

  • a / b – длины полуосей в пикселях (целое число).

  • rotation – поворот эллипса в градусах (целое число).

Это обычный кортеж, а не attrtuple, поэтому к полям можно обращаться только по индексу.

Константы

Форматы пикселей

Передайте любое из следующих значений в качестве аргумента pixformat конструктору Image или методу csi.CSI.pixformat().

image.BINARY: int

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

image.GRAYSCALE: int

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

image.RGB565: int

Цвет с 16 битами на пиксель, упакованный как 5 бит красного / 6 бит зелёного / 5 бит синего. Цветовой формат по умолчанию.

image.BAYER: int

Необработанные данные Байера с 8 битами на пиксель прямо с датчика. Большинство методов обработки изображений недоступны для изображений Байера; используйте это, когда хотите выполнять дебайеринг по запросу или хранить больше пикселей в меньшем объёме памяти.

image.YUV422: int

Цвет с цветностью, прореженной 4:2:2, два байта на пиксель, упакованный как Y1, U, Y2, V на пару пикселей. Только некоторые методы обработки изображений работают напрямую с YUV422.

image.JPEG: int

Сжатый буфер JPEG. Операции на уровне пикселей сначала требуют Image.to_grayscale() или Image.to_rgb565().

image.PNG: int

Сжатый буфер PNG. Операции на уровне пикселей сначала требуют Image.to_grayscale() или Image.to_rgb565().

Цветовые палитры

Передайте любое из следующих значений в Image.to_rainbow(), Image.to_ironbow(), Image.draw_image() (color_palette=) или в csi.CSI.color_palette(), чтобы раскрасить изображение в оттенках серого.

image.PALETTE_RAINBOW: int

Гладкое цветовое колесо радуги. Палитра OpenMV по умолчанию для тепловизионных изображений.

image.PALETTE_IRONBOW: int

Нелинейная палитра «ironbow», имитирующая вид видоискателя тепловизора FLIR Lepton.

image.PALETTE_DEPTH: int

Палитра для изображений глубины. Доступна только в сборках с поддержкой датчика глубины (конвейер ToF – например, OpenMV Cam AE3 или любая камера с подключённым модулем ToF Pmod).

image.PALETTE_EVT_DARK: int

Палитра для визуализации кадров событийной камеры GENX320 на тёмном фоне. Передайте в csi.CSI.color_palette, чтобы драйвер GENX320 выдавал раскрашенные кадры RGB565 в режиме гистограммы, или в Image.draw_image() color_palette= при раскрашивании событийного изображения в оттенках серого.

Доступна только в сборках с поддержкой GENX320 (OpenMV Cam AE3 и Pmod GENX320).

image.PALETTE_EVT_LIGHT: int

Палитра для визуализации кадров событийной камеры GENX320 на светлом фоне. Та же диспетчеризация и доступность, что и у PALETTE_EVT_DARK.

Режимы масштабирования

Передайте любое из следующих значений в качестве аргумента hint методам Image.draw_image(), Image.scale() или аналогичным методам масштабирования.

image.AREA: int

Масштабатор с усреднением по площади. Используется при уменьшении масштаба; для увеличения используется метод ближайшего соседа (Nearest-Neighbor).

image.BILINEAR: int

Билинейный масштабатор. Выполняет субдискретизацию при уменьшении масштаба.

image.BICUBIC: int

Бикубический масштабатор. Более высокое качество, чем BILINEAR, но медленнее. Выполняет субдискретизацию при уменьшении масштаба.

Подсказки рисования / draw_image

Объедините любые из них побитовым ИЛИ и передайте в качестве аргумента hint метода Image.draw_image().

image.VFLIP: int

Отразить источник по вертикали во время рисования.

image.HMIRROR: int

Отразить источник по горизонтали во время рисования.

image.TRANSPOSE: int

Транспонировать (поменять местами x/y) источник во время рисования.

image.CENTER: int

Центрировать источник на месте назначения. Любые явные смещения x/y тогда становятся смещениями от центра, а не от верхнего левого угла.

image.EXTRACT_RGB_CHANNEL_FIRST: int

При извлечении канала RGB через Image.draw_image() извлекать канал до масштабирования. Без этой подсказки канал извлекается после масштабирования.

image.APPLY_COLOR_PALETTE_FIRST: int

При применении цветовой палитры через Image.draw_image() применять палитру до масштабирования. Без этой подсказки палитра применяется после масштабирования.

image.SCALE_ASPECT_KEEP: int

Масштабировать источник так, чтобы он поместился внутри места назначения с сохранением соотношения сторон (добавляет поля при различных соотношениях).

image.SCALE_ASPECT_EXPAND: int

Масштабировать источник так, чтобы он заполнил место назначения с сохранением соотношения сторон (обрезает при различных соотношениях).

image.SCALE_ASPECT_IGNORE: int

Масштабировать источник так, чтобы он заполнил место назначения, игнорируя соотношение сторон.

image.BLACK_BACKGROUND: int

Сообщить пути альфа-смешивания, что место назначения заведомо чёрное, чтобы можно было пропустить считывание пикселя назначения. Ускоряет альфа-эффекты на только что очищенных буферах.

image.ROTATE_90: int

Сокращение для VFLIP | TRANSPOSE (поворот на 90 градусов по часовой стрелке).

image.ROTATE_180: int

Сокращение для HMIRROR | VFLIP (поворот на 180 градусов).

image.ROTATE_270: int

Сокращение для HMIRROR | TRANSPOSE (поворот на 270 градусов по часовой стрелке).

Субдискретизация JPEG

Передайте любое из следующих значений в качестве аргумента subsampling методам Image.to_jpeg(), Image.compress() или Image.save() при записи JPEG.

image.JPEG_SUBSAMPLING_AUTO: int

Выбрать субдискретизацию цветности автоматически на основе настройки качества JPEG.

image.JPEG_SUBSAMPLING_444: int

Принудительно использовать субдискретизацию цветности 4:4:4 (без сжатия цветности).

image.JPEG_SUBSAMPLING_422: int

Принудительно использовать субдискретизацию цветности 4:2:2. Рекомендуется при потоковой передаче MJPEG сторонним видеоплеерам, которые некорректно работают с 4:2:0.

image.JPEG_SUBSAMPLING_420: int

Принудительно использовать субдискретизацию цветности 4:2:0.

Сопоставление по шаблону

Передайте любое из следующих значений в качестве аргумента search методу Image.find_template().

image.SEARCH_EX: int

Исчерпывающий поиск – оценивает каждую позицию в ROI. Самый медленный, но гарантированно находит наилучшее совпадение.

image.SEARCH_DS: int

Алмазный поиск – поиск от грубого к точному, который намного быстрее, чем SEARCH_EX, но может пропустить глобальный оптимум на сильно самоподобных шаблонах.

Обнаружение границ

Передайте любое из следующих значений в качестве аргумента algorithm методу Image.find_edges().

image.EDGE_CANNY: int

Детектор границ Кэнни – величина градиента + подавление немаксимумов + гистерезис. Более высокое качество, медленнее.

image.EDGE_SIMPLE: int

Детектор границ на основе порогового высокочастотного фильтра. Быстрее, но даёт более толстые и зашумлённые границы, чем EDGE_CANNY.

Детекторы углов ORB

Передайте любое из следующих значений в качестве аргумента corner_detector методу Image.find_keypoints().

image.CORNER_FAST: int

Детектор углов FAST. Быстрее, чем CORNER_AGAST, но менее точный.

image.CORNER_AGAST: int

Детектор углов AGAST. Медленнее, чем CORNER_FAST, но даёт более стабильные ключевые точки.

Семейства AprilTag

Объедините побитовым ИЛИ любую комбинацию следующих значений и передайте в качестве аргумента families методу Image.find_apriltags(). Каждое семейство управляется собственной опцией сборки в прошивке; неподдерживаемые семейства отсутствуют во время выполнения, а не всегда равны нулю.

image.TAG16H5: int

Семейство AprilTag 16h5 (30 уникальных ID, 0-битная коррекция ошибок).

image.TAG25H9: int

Семейство AprilTag 25h9 (35 уникальных ID, до 3-битной коррекции ошибок).

image.TAG36H10: int

Семейство AprilTag 36h10 (2320 уникальных ID, до 3-битной коррекции ошибок).

image.TAG36H11: int

Семейство AprilTag 36h11 (587 уникальных ID, до 4-битной коррекции ошибок). Самое распространённое семейство.

image.TAGCIRCLE21H7: int

Семейство AprilTag Circle21h7.

image.TAGCIRCLE49H12: int

Семейство AprilTag Circle49h12.

image.TAGCUSTOM48H12: int

Семейство AprilTag Custom48h12.

image.TAGSTANDARD41H12: int

Семейство AprilTag Standard41h12.

image.TAGSTANDARD52H13: int

Семейство AprilTag Standard52h13.

Символики штрихкодов

Значения, сообщаемые в BarCode.type для записей, возвращаемых Image.find_barcodes().

image.EAN2: int

Дополнительный штрихкод EAN-2.

image.EAN5: int

Дополнительный штрихкод EAN-5.

image.EAN8: int

Штрихкод EAN-8.

image.UPCE: int

Штрихкод UPC-E.

image.ISBN10: int

Штрихкод ISBN-10.

image.UPCA: int

Штрихкод UPC-A.

image.EAN13: int

Штрихкод EAN-13.

image.ISBN13: int

Штрихкод ISBN-13.

image.I25: int

Штрихкод Interleaved 2-of-5.

image.DATABAR: int

Штрихкод GS1 DataBar.

image.DATABAR_EXP: int

Штрихкод GS1 DataBar Expanded.

image.CODABAR: int

Штрихкод Codabar.

image.CODE39: int

Штрихкод Code 39.

image.PDF417: int

Двумерный многоуровневый штрихкод PDF417. Константа существует для полноты, но декодер штрихкодов в настоящее время не реализует PDF417 – Image.find_barcodes() не будет возвращать обнаружения этого типа.

image.CODE93: int

Штрихкод Code 93.

image.CODE128: int

Штрихкод Code 128.