classe ImageIO – oggetto ImageIO

La classe ImageIO registra e riproduce flussi di frame Image nel formato su disco nativo di OpenMV. Un singolo flusso può contenere frame eterogenei (formati di pixel / dimensioni diversi) e registra l’intervallo tra i frame per ciascuno di essi, in modo che la riproduzione ricrei il frame rate originale.

Esistono due archivi di supporto:

  • Flusso su file – i frame vengono letti da / aggiunti a un file nel filesystem. Il file inizia con un’intestazione magica di 16 byte OMV IMG STR Vx.y seguita da blocchi per ciascun frame. Lo scrittore attuale emette V2.0; i file più vecchi V1.0 e V1.1 sono ancora leggibili.

  • Flusso in memoria – i frame vengono letti da / scritti in un buffer RAM di dimensione fissa allocato al momento della costruzione. Utile per far transitare i frame attraverso filtri che richiedono una registrazione senza toccare il filesystem.

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

Crea un flusso ImageIO.

Se path è una stringa, viene aperto un flusso su file in quel percorso. mode deve essere uno dei seguenti:

  • 'r' – apre un file esistente in lettura. L’intestazione magica viene convalidata e la versione (V1.0 / V1.1 / V2.0) viene registrata per l’uso da parte di version().

  • 'w' – tronca / crea il file e scrive una nuova intestazione magica V2.0. I frame vengono aggiunti a ogni write().

Se path è una tupla di 3 elementi (w, h, pixformat), viene allocato un flusso in memoria. mode è in tal caso il numero intero di slot per frame da pre-allocare. Il buffer è dimensionato per count frame di (w, h, pixformat) e non può crescere dopo la creazione. pixformat è uno tra image.BINARY, image.GRAYSCALE, image.RGB565, image.BAYER, image.YUV422, image.JPEG o image.PNG. Per i formati compressi (image.JPEG, image.PNG) la dimensione per slot è stimata a 2 bpp; i frame più grandi della stima sollevano ValueError al momento di write().

Ispezione

type() → int

Restituisce l’archivio di supporto del flusso: FILE_STREAM per un flusso su file, MEMORY_STREAM per un flusso in memoria.

is_closed() → bool

Restituisce True se close() è stata chiamata su questo oggetto. Una volta chiuso, il flusso solleva OSError("Stream closed") a ogni successiva operazione di lettura/scrittura/seek.

count() → int

Restituisce il numero di frame attualmente memorizzati nel flusso. Per i flussi su file questo valore cresce man mano che write() aggiunge frame; per i flussi in memoria è fisso al momento della costruzione.

offset() → int

Restituisce l’indice del frame corrente. Viene incrementato da read() e write(), e azzerato da seek().

version() → int | None

Restituisce la versione del formato su disco per i flussi su file (10 per V1.0, 11 per V1.1, 20 per V2.0). Restituisce None per i flussi in memoria.

buffer_size() → int | None

Restituisce la dimensione in byte del buffer di pixel per slot per i flussi in memoria (la dimensione dello slot meno l’intestazione di gestione interna di Image). Restituisce None per i flussi su file. Usalo insieme a count() per verificare se una determinata dimensione di frame entrerà.

size() → int

Restituisce il numero totale di byte consumati dal flusso – la dimensione del file su disco per i flussi su file, oppure la dimensione completa del buffer RAM (count * per_slot_size inclusa l’intestazione per slot) per i flussi in memoria.

I/O

write(img: Image) → ImageIO

Aggiunge (flusso su file) o memorizza all’offset (flusso in memoria) img e fa avanzare offset() di uno.

Per i flussi su file il file cresce man mano che vengono aggiunti i frame. Scrivere a un offset diverso da quello finale tronca il resto del file, quindi il conteggio può diminuire.

Per i flussi in memoria il frame viene scritto nello slot corrente; scrivere oltre l’ultimo slot solleva EOFError("End of stream") e scrivere un frame più grande di buffer_size() solleva ValueError("Invalid frame size").

Restituisce self in modo che le chiamate possano essere concatenate.

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

Legge il frame all’attuale offset(), fa avanzare l’offset e restituisce la nuova Image. Rispecchia la metà di riproduzione di write().

copy_to_fb – quando è True (predefinito) il frame decodificato viene collocato nel frame buffer della camera (lo stesso posto in cui finisce csi.CSI.snapshot()), in modo che l’oggetto Image restituito sia disegnabile tramite l’anteprima dell’IDE. Quando è False il frame viene invece allocato nell’heap di MicroPython.

loop (solo flussi su file) – quando è True (predefinito) la lettura oltre l’ultimo frame torna al primo frame e prosegue. Quando è False la chiamata restituisce None una volta raggiunta la fine del file.

pause – quando è True (predefinito) la chiamata si blocca finché non è trascorso l’intervallo tra i frame originariamente registrato, in modo che la riproduzione avvenga al frame rate nativo della registrazione. Imposta su False per una riproduzione il più veloce possibile.

seek(offset: int) → ImageIO

Sposta offset() al frame offset. offset deve essere non negativo; gli offset dei flussi in memoria devono inoltre essere inferiori a count().

I seek sui flussi su file percorrono il file frame per frame a partire dall’inizio, poiché i blocchi dei frame hanno dimensione variabile – per salti lunghi aspettati un tempo O(offset).

Restituisce self in modo che le chiamate possano essere concatenate.

sync() → ImageIO

Scarica le scritture in sospeso sul disco per i flussi su file (chiama la sync del filesystem sottostante). Non ha effetto per i flussi in memoria.

Restituisce self in modo che le chiamate possano essere concatenate.

close() → None

Chiude il flusso. Rilascia il buffer di memoria (flussi in memoria) o chiude il file (flussi su file). Dopo close() l’oggetto ImageIO non può essere riutilizzato; le operazioni successive sollevano OSError("Stream closed"). Chiamare close() due volte non ha effetto.

Un oggetto ImageIO viene chiuso automaticamente anche quando viene raccolto dal garbage collector (registra un finaliser al momento della costruzione).

Costanti

FILE_STREAM: int

Valore restituito da type() per i flussi basati su file.

MEMORY_STREAM: int

Valore restituito da type() per i flussi in memoria.