Skip to content

ImageIO

Note

Install with pip install labox[imageio]

Media Serializer

The MediaSerializer provides a serializer implementation for various types of media supported by the imageio library. Instead of passing data directly, it works with Media objects that wrap NumPy arrays with format metadata.

Basic Usage

A default instance of the serializer is available by importing media_serializer:

import numpy as np

from labox.extra.imageio import Media
from labox.extra.imageio import media_serializer

gen = np.random.Generator(np.random.PCG64())
image_data = gen.integers(0, 255, (100, 100, 3), dtype=np.uint8)
media = Media(data=image_data, extension=".png")

serialized_data = media_serializer.serialize_data(media)

You can also create a custom instance with specific MIME type configuration:

from mimetypes import MimeTypes

from labox.extra.imageio import MediaSerializer

custom_mimetypes = MimeTypes()
custom_mimetypes.add_type("image/webp", ".webp")

serializer = MediaSerializer(mimetypes=custom_mimetypes)

Media Data Types

The Media class wraps media data with format information:

from labox.extra.imageio import Media

# Single image
image = Media(
    data=image_array,
    extension=".jpg",  # Will determine content type automatically
)

# Video or image sequence
video = Media(
    data=[frame1, frame2, frame3],  # Sequence of arrays
    extension=".mp4",
)

# Using specific plugin instead of extension
media = Media(
    data=image_array,
    plugin="PNG-PIL",  # Use specific ImageIO plugin
)

Format Support

The serializer supports any format that ImageIO can handle, including:

  • Images: PNG, JPEG, GIF, TIFF, BMP, WebP, and many others
  • Videos: MP4, AVI, MOV, WebM (when appropriate codecs are available)
  • Scientific formats: DICOM, FIT, and other specialized formats

Format selection can be controlled in two ways:

Content Type Detection

The serializer automatically determines the MIME type based on the file extension using Python's mimetypes module. If no extension is provided or the type cannot be determined, it defaults to "application/octet-stream".

Configuration Persistence

The serializer stores the plugin and extension information in the serialized data's config, ensuring that media can be deserialized using the same format settings that were used during serialization. This is particularly important for maintaining compatibility when specific plugins or format options are required.