clase ImageIO – objeto ImageIO

La clase ImageIO graba y reproduce flujos de fotogramas Image en el formato nativo en disco de OpenMV. Un único flujo puede contener fotogramas heterogéneos (distintos formatos de píxel / tamaños) y registra el intervalo entre fotogramas de cada uno, de modo que la reproducción recrea la tasa de fotogramas original.

Existen dos almacenes de respaldo:

• Flujo de archivo – los fotogramas se leen de / se añaden a un archivo del sistema de archivos. El archivo comienza con una cabecera mágica de 16 bytes OMV IMG STR Vx.y seguida de fragmentos por fotograma. El escritor actual emite V2.0; los archivos más antiguos V1.0 y V1.1 aún se pueden leer.

• Flujo de memoria – los fotogramas se leen de / se escriben en un búfer de RAM de tamaño fijo asignado en el momento de la construcción. Útil para hacer pasar fotogramas por filtros que necesitan una grabación sin tocar el sistema de archivos.

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

Crea un flujo ImageIO.

Si path es una cadena, se abre un flujo de archivo en esa ruta. mode debe ser uno de:

• 'r' – abre un archivo existente para lectura. Se valida la cabecera mágica y se registra la versión (V1.0 / V1.1 / V2.0) para que la use version().

• 'w' – trunca / crea el archivo y escribe una nueva cabecera mágica V2.0. Los fotogramas se añaden en cada write().

Si path es una 3-tupla (w, h, pixformat), se asigna un flujo de memoria. En ese caso mode es el número entero de ranuras de fotograma a preasignar. El búfer se dimensiona para count fotogramas de (w, h, pixformat) y no se permite que crezca tras su creación. pixformat es uno de image.BINARY, image.GRAYSCALE, image.RGB565, image.BAYER, image.YUV422, image.JPEG o image.PNG. Para los formatos comprimidos (image.JPEG, image.PNG) el tamaño por ranura se estima en 2 bpp; los fotogramas mayores que la estimación lanzan ValueError en el momento de write().

Inspección

type() → int

Devuelve el almacén de respaldo del flujo: FILE_STREAM para un flujo de archivo, MEMORY_STREAM para un flujo de memoria.

is_closed() → bool

Devuelve True si se ha llamado a close() sobre este objeto. Una vez cerrado, el flujo lanza OSError("Stream closed") ante cualquier lectura/escritura/búsqueda posterior.

count() → int

Devuelve el número de fotogramas almacenados actualmente en el flujo. Para los flujos de archivo este valor crece a medida que write() añade fotogramas; para los flujos de memoria es fijo desde el momento de la construcción.

offset() → int

Devuelve el índice del fotograma actual. Se incrementa con read() y write(), y se reinicia con seek().

version() → int | None

Devuelve la versión del formato en disco para los flujos de archivo (10 para V1.0, 11 para V1.1, 20 para V2.0). Devuelve None para los flujos de memoria.

buffer_size() → int | None

Devuelve el tamaño en bytes del búfer de píxeles por ranura para los flujos de memoria (el tamaño de la ranura menos la cabecera interna de control de la Image). Devuelve None para los flujos de archivo. Úsalo junto con count() para comprobar si un tamaño de fotograma concreto cabrá.

size() → int

Devuelve el total de bytes consumidos por el flujo: el tamaño del archivo en disco para los flujos de archivo, o el tamaño completo del búfer de RAM (count * per_slot_size incluyendo la cabecera por ranura) para los flujos de memoria.

E/S

write(img: Image) → ImageIO

Añade (flujo de archivo) o almacena en el desplazamiento (flujo de memoria) img y avanza offset() en uno.

Para los flujos de archivo, el archivo crece a medida que se añaden fotogramas. Escribir en un desplazamiento que no sea el final trunca el resto del archivo, de modo que el recuento puede reducirse.

Para los flujos de memoria, el fotograma se escribe en la ranura actual; escribir más allá de la última ranura lanza EOFError("End of stream") y escribir un fotograma mayor que buffer_size() lanza ValueError("Invalid frame size").

Devuelve self para que las llamadas se puedan encadenar.

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

Lee el fotograma en el offset() actual, avanza el desplazamiento y devuelve la nueva Image. Es el reflejo de reproducción de la mitad de write().

copy_to_fb – cuando es True (predeterminado), el fotograma decodificado se coloca en el búfer de fotogramas (frame buffer) de la cámara (el mismo lugar donde aterriza un csi.CSI.snapshot()), de modo que la Image devuelta se puede dibujar a través de la vista previa del IDE. Cuando es False, el fotograma se asigna en el montículo de MicroPython.

loop (solo flujos de archivo) – cuando es True (predeterminado), leer más allá del último fotograma vuelve al primer fotograma y continúa. Cuando es False, la llamada devuelve None una vez alcanzado el final del archivo.

pause – cuando es True (predeterminado), la llamada se bloquea hasta que haya transcurrido el intervalo entre fotogramas grabado originalmente, de modo que la reproducción se ejecuta a la tasa de fotogramas nativa de la grabación. Establécelo en False para una reproducción lo más rápida posible.

seek(offset: int) → ImageIO

Mueve offset() al fotograma offset. offset debe ser no negativo; los desplazamientos de los flujos de memoria también deben ser menores que count().

Las búsquedas en flujos de archivo recorren el archivo fotograma a fotograma desde el principio, dado que los fragmentos de fotograma son de tamaño variable; espera un tiempo O(offset) para saltos grandes.

Devuelve self para que las llamadas se puedan encadenar.

sync() → ImageIO

Vuelca a disco las escrituras pendientes en los flujos de archivo (llama al sync del sistema de archivos subyacente). No tiene efecto en los flujos de memoria.

Devuelve self para que las llamadas se puedan encadenar.

close() → None

Cierra el flujo. Libera el búfer de memoria (flujos de memoria) o cierra el archivo (flujos de archivo). Tras close() el objeto ImageIO no se puede reutilizar; las operaciones posteriores lanzan OSError("Stream closed"). Llamar a close() dos veces no tiene efecto.

Un ImageIO también se cierra automáticamente cuando se recolecta como basura (registra un finalizador en el momento de la construcción).

Constantes

FILE_STREAM: int

Valor devuelto por type() para los flujos respaldados por archivo.

MEMORY_STREAM: int

Valor devuelto por type() para los flujos en memoria.