класс ImageIO – объект ImageIO

Класс ImageIO записывает и воспроизводит потоки кадров Image во встроенном дисковом формате OpenMV. Один поток может содержать разнородные кадры (с разными форматами пикселей / размерами) и записывает межкадровый интервал для каждого из них, поэтому при воспроизведении восстанавливается исходная частота кадров.

Существует два хранилища:

• Файловый поток – кадры читаются из файла в файловой системе или дописываются в него. Файл начинается с 16-байтного магического заголовка OMV IMG STR Vx.y, за которым следуют покадровые фрагменты. Текущий писатель создаёт V2.0; более старые файлы V1.0 и V1.1 по-прежнему доступны для чтения.

• Поток в памяти – кадры читаются из буфера ОЗУ фиксированного размера, выделяемого при создании, или записываются в него. Полезно для прогона кадров через фильтры, которым нужна запись, без обращения к файловой системе.

class image.ImageIO(path: str | Tuple[int, int, int], mode: str | int)

Создаёт поток ImageIO.

Если path – это строка, открывается файловый поток по этому пути. mode должен принимать одно из значений:

• 'r' – открыть существующий файл для чтения. Магический заголовок проверяется, а версия (V1.0 / V1.1 / V2.0) запоминается для использования методом version().

• 'w' – усечь / создать файл и записать новый магический заголовок V2.0. Кадры дописываются при каждом вызове write().

Если path – это 3-элементный кортеж (w, h, pixformat), выделяется поток в памяти. mode в этом случае является целочисленным количеством слотов кадров для предварительного выделения. Буфер рассчитан на count кадров формата (w, h, pixformat) и не может расти после создания. pixformat – одно из значений image.BINARY, image.GRAYSCALE, image.RGB565, image.BAYER, image.YUV422, image.JPEG или image.PNG. Для сжатых форматов (image.JPEG, image.PNG) размер слота оценивается как 2 bpp; кадры, превышающие эту оценку, вызывают ValueError при вызове write().

Проверка

type() → int

Возвращает хранилище потока: FILE_STREAM для файлового потока, MEMORY_STREAM для потока в памяти.

is_closed() → bool

Возвращает True, если для этого объекта был вызван метод close(). После закрытия поток вызывает OSError("Stream closed") при любой последующей операции чтения/записи/перемещения.

count() → int

Возвращает количество кадров, хранящихся в потоке в данный момент. Для файловых потоков оно растёт по мере того, как write() дописывает кадры; для потоков в памяти оно фиксируется при создании.

offset() → int

Возвращает текущий индекс кадра. Увеличивается методами read() и write(), сбрасывается методом seek().

version() → int | None

Возвращает версию дискового формата для файловых потоков (10 для V1.0, 11 для V1.1, 20 для V2.0). Возвращает None для потоков в памяти.

buffer_size() → int | None

Возвращает размер буфера пикселей одного слота в байтах для потоков в памяти (размер слота за вычетом внутреннего служебного заголовка Image). Возвращает None для файловых потоков. Используйте это вместе с count(), чтобы проверить, поместится ли кадр определённого размера.

size() → int

Возвращает общее число байтов, занимаемых потоком, – размер файла на диске для файловых потоков или полный размер буфера ОЗУ (count * per_slot_size с учётом заголовка каждого слота) для потоков в памяти.

Ввод/вывод

write(img: Image) → ImageIO

Дописывает (файловый поток) или сохраняет по смещению (поток в памяти) img и увеличивает offset() на единицу.

Для файловых потоков файл растёт по мере дописывания кадров. Запись по смещению, отличному от конца, усекает остаток файла, поэтому количество может уменьшиться.

Для потоков в памяти кадр записывается в текущий слот; запись за последний слот вызывает EOFError("End of stream"), а запись кадра, превышающего buffer_size(), вызывает ValueError("Invalid frame size").

Возвращает self, поэтому вызовы можно объединять в цепочку.

read(copy_to_fb: bool = True, *, loop: bool = True, pause: bool = True) → Image | None

Читает кадр по текущему offset(), увеличивает смещение и возвращает новый Image. Зеркально отражает воспроизводящую половину write().

copy_to_fb – если True (по умолчанию), декодированный кадр помещается в буфер кадра камеры (туда же, куда попадает результат csi.CSI.snapshot()), поэтому возвращаемый Image можно рисовать через предпросмотр IDE. Если False, кадр выделяется в куче MicroPython.

loop (только для файловых потоков) – если True (по умолчанию), чтение за последним кадром возвращается к первому кадру и продолжается. Если False, вызов возвращает None по достижении конца файла.

pause – если True (по умолчанию), вызов блокируется, пока не истечёт исходно записанный межкадровый интервал, поэтому воспроизведение идёт с собственной частотой кадров записи. Установите False для максимально быстрого воспроизведения.

seek(offset: int) → ImageIO

Перемещает offset() к кадру offset. offset должен быть неотрицательным; смещения потока в памяти также должны быть меньше count().

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

Возвращает self, поэтому вызовы можно объединять в цепочку.

sync() → ImageIO

Сбрасывает ожидающие записи на диск для файловых потоков (вызывает sync нижележащей файловой системы). Не выполняет действий для потоков в памяти.

Возвращает self, поэтому вызовы можно объединять в цепочку.

close() → None

Закрывает поток. Освобождает буфер памяти (потоки в памяти) или закрывает файл (файловые потоки). После close() объект ImageIO нельзя использовать повторно; последующие операции вызывают OSError("Stream closed"). Повторный вызов close() не выполняет никаких действий.

Объект ImageIO также закрывается автоматически при сборке мусора (при создании он регистрирует финализатор).

Константы

FILE_STREAM: int

Значение, возвращаемое методом type() для потоков с файловым хранилищем.

MEMORY_STREAM: int

Значение, возвращаемое методом type() для потоков в памяти.