or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

formats-plugins.mdimage-io.mdindex.mdmulti-image.mdreader-writer.mdv3-api.mdvolume-data.md
tile.json

tessl/pypi-imageio

Library for reading and writing a wide range of image, video, scientific, and volumetric data formats.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/imageio@2.37.x

To install, run

npx @tessl/cli install tessl/pypi-imageio@2.37.0

index.mddocs/

ImageIO

A comprehensive Python library that provides an easy interface to read and write a wide range of image data, including animated images, volumetric data, and scientific formats. ImageIO serves as a universal I/O library for images and videos, supporting 20+ formats through its plugin architecture while maintaining cross-platform compatibility.

Package Information

  • Package Name: imageio
  • Type: Image Processing Library
  • Language: Python
  • Installation: pip install imageio
  • Dependencies: numpy, pillow >= 8.3.2

Core Imports

import imageio

Common usage patterns:

# v2 API (current stable)
import imageio.v2 as imageio

# v3 API (modern interface)
import imageio.v3 as iio

Basic Usage

import imageio.v2 as imageio
import numpy as np

# Read a single image
image = imageio.imread('path/to/image.jpg')
print(f"Image shape: {image.shape}")

# Write a single image
imageio.imwrite('output.png', image)

# Read multiple images (like GIF frames)
images = imageio.mimread('animation.gif')
print(f"Number of frames: {len(images)}")

# Write multiple images as GIF
imageio.mimwrite('output.gif', images, duration=0.5)

# Read volume data (3D medical/scientific)
volume = imageio.volread('scan.tiff')
print(f"Volume shape: {volume.shape}")

# Modern v3 API example
import imageio.v3 as iio

# Read with explicit control
image = iio.imread('image.jpg', index=0)

# Iterate through images in a file
for frame in iio.imiter('animation.gif'):
    print(f"Frame shape: {frame.shape}")

# Get image properties without loading pixel data
props = iio.improps('image.jpg')
print(f"Shape: {props.shape}, dtype: {props.dtype}")

Architecture

ImageIO uses a plugin-based architecture that provides format flexibility:

  • Format Plugins: 20+ specialized plugins for different file formats (DICOM, TIFF, FFmpeg, PIL, etc.)
  • Legacy v2 API: Backward-compatible interface with explicit data type handling (images, volumes)
  • Modern v3 API: Streamlined interface with unified resource handling and context managers
  • Plugin Management: Automatic format detection with manual override capabilities
  • Resource Abstraction: Supports files, URLs, bytes, file objects, and pathlib.Path

This design enables ImageIO to handle diverse formats while providing consistent APIs for scientific computing, computer vision, and multimedia applications.

Capabilities

Module Imports

Direct access to ImageIO's API versions and configuration modules for advanced usage and customization.

# API version modules
import imageio.v2  # Legacy v2 API
import imageio.v3  # Modern v3 API

# Configuration and plugin access
import imageio.config  # Plugin and format configuration
import imageio.plugins  # Plugin registry and implementations

Image I/O Operations

Core functionality for reading and writing single images, supporting all major image formats with automatic format detection and metadata preservation.

def imread(uri, format=None, **kwargs):
    """Read a single image from file, URL, or bytes."""

def imwrite(uri, im, format=None, **kwargs):
    """Write a single image to file or return as bytes."""

Image I/O Operations

Multi-Image Operations

Handle sequences of images like GIF animations, TIFF stacks, or video frames with memory management and batch processing capabilities.

def mimread(uri, format=None, memtest="256MB", **kwargs):
    """Read multiple images with memory protection."""

def mimwrite(uri, ims, format=None, **kwargs):
    """Write multiple images as animation or stack."""

Multi-Image Operations

Volume Data Handling

Support for 3D volumetric data commonly used in medical imaging, scientific visualization, and microscopy applications.

def volread(uri, format=None, **kwargs):
    """Read 3D volume data (NxMxL arrays)."""

def volwrite(uri, vol, format=None, **kwargs):
    """Write 3D volume data to file."""

def mvolread(uri, format=None, memtest="1GB", **kwargs):
    """Read multiple volumes with memory protection."""

def mvolwrite(uri, vols, format=None, **kwargs):
    """Write multiple volumes to file."""

Volume Data Handling

Modern v3 API

Streamlined interface with context managers, unified resource handling, and enhanced metadata access for modern Python development.

def imopen(uri, io_mode, **kwargs):
    """Open image resource as context manager."""

def imiter(uri, **kwargs):
    """Iterate over images in a file."""

def improps(uri, **kwargs):
    """Get standardized image properties."""

def immeta(uri, **kwargs):
    """Get format-specific metadata."""

Modern v3 API

Reader/Writer Objects

Low-level interfaces for manual control over reading and writing operations with fine-grained parameter access.

def get_reader(uri, format=None, mode="?", **kwargs):
    """Get reader object for manual reading."""

def get_writer(uri, format=None, mode="?", **kwargs):
    """Get writer object for manual writing."""

Reader/Writer Objects

Format and Plugin Management

Tools for discovering available formats, getting format-specific help, and managing the plugin system.

def help(name=None):
    """Show format documentation or list formats."""

# Format manager access
formats: FormatManager
show_formats: callable

Format and Plugin Management

Types

# Type aliases for input/output
ImageResource = Union[str, bytes, BytesIO, Path, BinaryIO]
ArrayLike = Union[np.ndarray, list, tuple]

# Core array type with metadata
class Array(np.ndarray):
    """NumPy array with attached metadata dictionary."""
    meta: dict

# V3 standardized properties
@dataclass
class ImageProperties:
    shape: Tuple[int, ...]
    dtype: np.dtype
    n_images: Optional[int] = None
    is_batch: bool = False
    spacing: Optional[tuple] = None

# Format management
class FormatManager:
    """Registry and manager for format plugins."""
    def show(self) -> None: ...
    def __getitem__(self, name: str) -> Format: ...

class Format:
    """Base class for format plugins."""
    class Reader: ...
    class Writer: ...

# Plugin base classes
class PluginV3:
    """Base class for v3 plugins."""
    def read(self, **kwargs) -> np.ndarray: ...
    def write(self, image: ArrayLike, **kwargs): ...
    def properties(self, **kwargs) -> ImageProperties: ...
    def metadata(self, **kwargs) -> dict: ...

# Constants
RETURN_BYTES: str  # Special URI for returning bytes