image.ImageIO – Image Stream

[中文]

The image.ImageIO type records and replays sequences of images while preserving inter-frame timing. A file stream reads/writes a container on storage; a memory stream keeps frames in a pre-allocated buffer. It is exposed on the image module as image.ImageIO; the type stub lives in stubs/imageio.pyi.

Record to Storage

import sensor, image

stream = image.ImageIO("/sdcard/stream.bin", "w")
for _ in range(30):
    stream.write(sensor.snapshot())
stream.sync()
print("frames:", stream.count(), "bytes:", stream.size())
stream.close()

Each write() stores the image and the elapsed time since the previous frame. sync() flushes buffered file data without closing the stream. Always close a file stream so the container metadata and storage buffers are finalized.

Replay a Recorded Stream

import image

stream = image.ImageIO("/sdcard/stream.bin", "r")
try:
    while True:
        img = stream.read(loop=False, pause=True)
        if img is None:
            break
        img.flush()
finally:
    stream.close()

pause=True reproduces the recorded frame timing, while loop=False returns None at the end instead of rewinding. Set pause=False when frames should be consumed as quickly as processing permits.

Use an In-Memory Stream

stream = image.ImageIO((320, 240, image.RGB565), 10)
for _ in range(10):
    stream.write(sensor.snapshot())

stream.seek(0)
first = stream.read(pause=False)
print("buffer bytes:", stream.buffer_size())
stream.close()

Memory streams avoid storage I/O and are useful for short frame histories or frame-difference workflows, but their full capacity is allocated in RAM or PSRAM when the stream is created.

Constants

imageio.FILE_STREAM: Stream backed by a file on storage (e.g. /sdcard/stream.bin).

imageio.MEMORY_STREAM: Stream backed by a fixed-size buffer in PSRAM/RAM.

Classes

class imageio.ImageIO(stream, mode)

class imageio.ImageIO(stream, count)

Record and replay sequences of images, preserving inter-frame timing. Exposed as image.ImageIO. A file stream reads/writes the OpenMV “OMV IMG STR” container on storage; a memory stream keeps frames in a pre-allocated buffer for fast capture/playback.

Open a file stream for reading (“r”) or writing (“w”).

Parameters:

stream – path to the stream file.
mode – “r” to read, “w” to create/overwrite.

type(): Return the stream type: FILE_STREAM or MEMORY_STREAM.

is_closed(): Return True if the stream has been closed.

count(): Return the number of frames recorded in the stream.

offset(): Return the current frame index (read/write cursor).

version(): Return the container version for file streams, or None for memory streams.

buffer_size(): Return the per-frame buffer size for memory streams, or None for file streams.

size(): Return the total stream size in bytes.

write(image)

Append one image to the stream (records the elapsed time since the last write).

Parameters:: image – frame to store.

read(copy_to_fb=..., *, loop=..., pause=...)

Read the next frame from the stream.

Parameters:

copy_to_fb – True loads the frame into the frame buffer (and updates the preview).
loop – True rewinds to the first frame at end-of-stream instead of returning None.
pause – True sleeps to honor the frame’s recorded timestamp (real-time playback).

seek(offset)

Move the read/write cursor to the given frame index.

Parameters:: offset – target frame index.

sync(): Flush buffered file data to storage (no-op for memory streams).

close(): Close the stream and release its resources.