classe ImageIO – objeto ImageIO

A classe ImageIO grava e reproduz fluxos de quadros Image no formato nativo em disco do OpenMV. Um único fluxo pode conter quadros heterogêneos (formatos de pixel / tamanhos diferentes) e registra o intervalo entre quadros de cada um, de modo que a reprodução recria a taxa de quadros original.

Há dois armazenamentos de apoio:

• Fluxo de arquivo – os quadros são lidos de / anexados a um arquivo no sistema de arquivos. O arquivo começa com um cabeçalho mágico de 16 bytes OMV IMG STR Vx.y seguido por blocos por quadro. O escritor atual emite V2.0; arquivos mais antigos V1.0 e V1.1 ainda podem ser lidos.

• Fluxo de memória – os quadros são lidos de / escritos em um buffer de RAM de tamanho fixo alocado no momento da construção. Útil para passar quadros por filtros que precisam de uma gravação sem tocar no sistema de arquivos.

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

Cria um fluxo ImageIO.

Se path for uma string, um fluxo de arquivo é aberto nesse caminho. mode deve ser um dos seguintes:

• 'r' – abre um arquivo existente para leitura. O cabeçalho mágico é validado e a versão (V1.0 / V1.1 / V2.0) é registrada para uso por version().

• 'w' – trunca / cria o arquivo e escreve um cabeçalho mágico V2.0 novo. Os quadros são anexados a cada write().

Se path for uma 3-tupla (w, h, pixformat), um fluxo de memória é alocado. Nesse caso mode é o número inteiro de slots de quadro a pré-alocar. O buffer é dimensionado para count quadros de (w, h, pixformat) e não pode crescer após a criação. pixformat é um dos valores image.BINARY, image.GRAYSCALE, image.RGB565, image.BAYER, image.YUV422, image.JPEG ou image.PNG. Para os formatos comprimidos (image.JPEG, image.PNG) o tamanho por slot é estimado em 2 bpp; quadros maiores que a estimativa geram ValueError no momento de write().

Inspeção

type() → int

Retorna o armazenamento de apoio do fluxo: FILE_STREAM para um fluxo de arquivo, MEMORY_STREAM para um fluxo de memória.

is_closed() → bool

Retorna True se close() foi chamado neste objeto. Uma vez fechado, o fluxo gera OSError("Stream closed") em qualquer leitura/escrita/busca posterior.

count() → int

Retorna o número de quadros atualmente armazenados no fluxo. Para fluxos de arquivo, isso cresce à medida que write() anexa quadros; para fluxos de memória, é fixado no momento da construção.

offset() → int

Retorna o índice do quadro atual. Incrementado por read() e write(), redefinido por seek().

version() → int | None

Retorna a versão do formato em disco para fluxos de arquivo (10 para V1.0, 11 para V1.1, 20 para V2.0). Retorna None para fluxos de memória.

buffer_size() → int | None

Retorna o tamanho em bytes do buffer de pixels por slot para fluxos de memória (o tamanho do slot menos o cabeçalho interno de controle do Image). Retorna None para fluxos de arquivo. Use isto junto com count() para verificar se um determinado tamanho de quadro caberá.

size() → int

Retorna o total de bytes consumidos pelo fluxo – o tamanho do arquivo em disco para fluxos de arquivo, ou o tamanho total do buffer de RAM (count * per_slot_size incluindo o cabeçalho por slot) para fluxos de memória.

E/S

write(img: Image) → ImageIO

Anexa (fluxo de arquivo) ou armazena no offset (fluxo de memória) img e avança offset() em uma posição.

Para fluxos de arquivo o arquivo cresce à medida que os quadros são anexados. Escrever em um offset que não seja o final trunca o restante do arquivo, de modo que a contagem pode diminuir.

Para fluxos de memória o quadro é escrito no slot atual; escrever além do último slot gera EOFError("End of stream") e escrever um quadro maior que buffer_size() gera ValueError("Invalid frame size").

Retorna self, de modo que as chamadas podem ser encadeadas.

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

Lê o quadro no offset() atual, avança o offset e retorna a nova Image. Espelha a metade de reprodução de write().

copy_to_fb – quando True (padrão), o quadro decodificado é colocado no frame buffer da câmera (o mesmo lugar onde um csi.CSI.snapshot() é depositado), de modo que a Image retornada pode ser desenhada através da pré-visualização do IDE. Quando False, o quadro é alocado no heap do MicroPython em vez disso.

loop (somente fluxos de arquivo) – quando True (padrão), ler além do último quadro retorna ao primeiro quadro e continua. Quando False, a chamada retorna None assim que o final do arquivo é alcançado.

pause – quando True (padrão), a chamada bloqueia até que o intervalo entre quadros originalmente gravado tenha decorrido, de modo que a reprodução ocorre na taxa de quadros nativa da gravação. Defina como False para reprodução o mais rápido possível.

seek(offset: int) → ImageIO

Move offset() para o quadro offset. offset deve ser não negativo; offsets de fluxos de memória também devem ser menores que count().

As buscas em fluxos de arquivo percorrem o arquivo quadro a quadro a partir do início, já que os blocos de quadro têm tamanho variável – espere tempo O(offset) para grandes saltos.

Retorna self, de modo que as chamadas podem ser encadeadas.

sync() → ImageIO

Descarrega as escritas pendentes para o disco em fluxos de arquivo (chama o sync subjacente do sistema de arquivos). Não tem efeito para fluxos de memória.

Retorna self, de modo que as chamadas podem ser encadeadas.

close() → None

Fecha o fluxo. Libera o buffer de memória (fluxos de memória) ou fecha o arquivo (fluxos de arquivo). Após close() o objeto ImageIO não pode ser reutilizado; operações subsequentes geram OSError("Stream closed"). Chamar close() duas vezes não tem efeito.

Um ImageIO também é fechado automaticamente quando é coletado pelo coletor de lixo (registra um finalizador na construção).

Constantes

FILE_STREAM: int

Valor retornado por type() para fluxos apoiados em arquivo.

MEMORY_STREAM: int

Valor retornado por type() para fluxos em memória.