class ImageIO – objeto ImageIO

A classe ImageIO regista e reproduz sequências de fotogramas Image no formato nativo do OpenMV em disco. Uma única sequência pode conter fotogramas heterogéneos (diferentes formatos de pixel / tamanhos) e regista o intervalo entre fotogramas de cada um, de modo a que a reprodução recrie a taxa de fotogramas original.

Existem dois tipos de armazenamento:

• Sequência de ficheiro – os fotogramas são lidos / adicionados a um ficheiro no sistema de ficheiros. O ficheiro começa com um cabeçalho mágico de 16 bytes OMV IMG STR Vx.y seguido de blocos por fotograma. O escritor atual emite V2.0; ficheiros mais antigos V1.0 e V1.1 ainda são legíveis.

• Sequência de memória – os fotogramas são lidos / escritos num buffer de RAM de tamanho fixo alocado no momento da construção. Útil para passar fotogramas por filtros que necessitam de uma gravação sem aceder ao sistema de ficheiros.

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

Cria uma sequência ImageIO.

Se path for uma cadeia de caracteres, é aberta uma sequência de ficheiro nesse caminho. mode deve ser um dos seguintes:

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

• 'w' – trunca / cria o ficheiro e escreve um novo cabeçalho mágico V2.0. Os fotogramas são adicionados em cada chamada a write().

Se path for uma 3-tupla (w, h, pixformat), é alocada uma sequência de memória. mode é então o número inteiro de posições de fotograma a pré-alocar. O buffer é dimensionado para count fotogramas de (w, h, pixformat) e não pode crescer após a criação. pixformat é um dos seguintes: 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 posição é estimado em 2 bpp; fotogramas maiores que a estimativa lançam ValueError no momento de write().

Inspeção

type() → int

Devolve o tipo de armazenamento da sequência: FILE_STREAM para uma sequência de ficheiro, MEMORY_STREAM para uma sequência de memória.

is_closed() → bool

Devolve True se close() tiver sido chamado neste objeto. Uma vez fechado, a sequência lança OSError("Stream closed") em qualquer leitura/escrita/posicionamento subsequente.

count() → int

Devolve o número de fotogramas atualmente armazenados na sequência. Para sequências de ficheiro este valor cresce à medida que write() adiciona fotogramas; para sequências de memória é fixo no momento da construção.

offset() → int

Devolve o índice do fotograma atual. Incrementado por read() e write(), reposto por seek().

version() → int | None

Devolve a versão do formato em disco para sequências de ficheiro (10 para V1.0, 11 para V1.1, 20 para V2.0). Devolve None para sequências de memória.

buffer_size() → int | None

Devolve o tamanho do buffer de pixel por posição em bytes para sequências de memória (o tamanho da posição menos o cabeçalho interno de gestão de Image). Devolve None para sequências de ficheiro. Use isto em conjunto com count() para verificar se um fotograma de determinado tamanho caberá.

size() → int

Devolve o total de bytes consumidos pela sequência – o tamanho do ficheiro em disco para sequências de ficheiro, ou o tamanho total do buffer em RAM (count * per_slot_size incluindo o cabeçalho por posição) para sequências de memória.

E/S

write(img: Image) → ImageIO

Adiciona (sequência de ficheiro) ou armazena na posição atual (sequência de memória) img e avança offset() em um.

Para sequências de ficheiro, o ficheiro cresce à medida que os fotogramas são adicionados. Escrever numa posição que não seja o fim trunca o resto do ficheiro, podendo reduzir a contagem.

Para sequências de memória, o fotograma é escrito na posição atual; escrever além da última posição lança EOFError("End of stream") e escrever um fotograma maior que buffer_size() lança ValueError("Invalid frame size").

Devolve self para que as chamadas possam ser encadeadas.

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

Lê o fotograma na offset() atual, avança o offset e devolve o novo Image. Corresponde à metade de reprodução de write().

copy_to_fb – quando True (predefinição) o fotograma descodificado é colocado no buffer de fotograma da câmara (o mesmo local onde aterra um csi.CSI.snapshot()), pelo que o Image devolvido pode ser visualizado através da pré-visualização do IDE. Quando False o fotograma é alocado na heap do MicroPython.

loop (apenas para sequências de ficheiro) – quando True (predefinição) a leitura além do último fotograma regressa ao primeiro e continua. Quando False a chamada devolve None após atingir o fim do ficheiro.

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

seek(offset: int) → ImageIO

Move offset() para o fotograma offset. offset deve ser não negativo; os offsets de sequências de memória também devem ser inferiores a count().

Os posicionamentos em sequências de ficheiro percorrem o ficheiro fotograma a fotograma a partir do início, uma vez que os blocos de fotograma têm tamanho variável – espere tempo O(offset) para grandes deslocamentos.

Devolve self para que as chamadas possam ser encadeadas.

sync() → ImageIO

Envia para disco as escritas pendentes em sequências de ficheiro (chama o sync do sistema de ficheiros subjacente). Sem efeito para sequências de memória.

Devolve self para que as chamadas possam ser encadeadas.

close() → None

Fecha a sequência. Liberta o buffer de memória (sequências de memória) ou fecha o ficheiro (sequências de ficheiro). Após close() o objeto ImageIO não pode ser reutilizado; operações subsequentes lançam OSError("Stream closed"). Chamar close() duas vezes não tem efeito.

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

Constantes

FILE_STREAM: int

Valor devolvido por type() para sequências suportadas por ficheiro.

MEMORY_STREAM: int

Valor devolvido por type() para sequências em memória.