tessl/pypi-imageio

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

—

Pending

Overview

Eval results

Files

Image I/O Operations

Name: tessl/pypi-imageio
Author: tessl

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

Capabilities

Single Image Reading

Read a single image from various sources including files, URLs, bytes, and file objects. Returns a numpy array with metadata attached.

def imread(uri, format=None, **kwargs):
    """
    Read an image from the specified file.
    
    Parameters:
    - uri (ImageResource): File path, URL, bytes, or file object
    - format (str, optional): Format to use for reading
    - **kwargs: Format-specific parameters
    
    Returns:
    - Array: NumPy array with 'meta' attribute containing metadata
    
    Note: Main imageio.imread shows deprecation warning, use imageio.v2.imread
    """

Usage Examples:

import imageio.v2 as imageio

# Read from file path
image = imageio.imread('photo.jpg')
print(f"Shape: {image.shape}, dtype: {image.dtype}")
print(f"Metadata: {image.meta}")

# Read from URL
image = imageio.imread('https://example.com/image.png')

# Read with specific format
image = imageio.imread('data.raw', format='RAW-FI')

# Read from bytes
with open('image.jpg', 'rb') as f:
    data = f.read()
image = imageio.imread(data)

Single Image Writing

Write a single image to file or return as bytes. Supports automatic format detection based on file extension.

def imwrite(uri, im, format=None, **kwargs):
    """
    Write an image to the specified file.
    
    Parameters:
    - uri (ImageResource): Output path or '<bytes>' for byte return
    - im (ArrayLike): Image data as numpy array (NxM, NxMx3, or NxMx4)
    - format (str, optional): Format to use for writing
    - **kwargs: Format-specific parameters (quality, compression, etc.)
    
    Returns:
    - None: When writing to file
    - bytes: When uri is '<bytes>'
    
    Raises:
    - ValueError: If image dimensions are invalid
    """

Usage Examples:

import imageio.v2 as imageio
import numpy as np

# Create sample image
image = np.random.randint(0, 255, (100, 100, 3), dtype=np.uint8)

# Write to file (format auto-detected from extension)
imageio.imwrite('output.png', image)

# Write with specific format and quality
imageio.imwrite('output.jpg', image, format='JPEG', quality=95)

# Get image as bytes
png_bytes = imageio.imwrite('<bytes>', image, format='PNG')

# Write grayscale image
gray_image = np.random.randint(0, 255, (100, 100), dtype=np.uint8)
imageio.imwrite('gray.png', gray_image)

# Write with transparency (RGBA)
rgba_image = np.random.randint(0, 255, (100, 100, 4), dtype=np.uint8)
imageio.imwrite('transparent.png', rgba_image)

Format-Specific Parameters

Different formats support various parameters for fine-tuning the I/O operations:

JPEG Parameters:

quality (int): JPEG quality (0-100, default varies)
optimize (bool): Optimize Huffman tables
progressive (bool): Save as progressive JPEG

PNG Parameters:

compress_level (int): Compression level (0-9)
optimize (bool): Optimize palette

TIFF Parameters:

compression (str): Compression type ('lzw', 'jpeg', 'packbits', etc.)
photometric (str): Photometric interpretation

Example with format parameters:

# High-quality JPEG with optimization
imageio.imwrite('high_quality.jpg', image, 
                quality=98, optimize=True, progressive=True)

# Compressed PNG
imageio.imwrite('compressed.png', image, 
                compress_level=9, optimize=True)

# TIFF with LZW compression
imageio.imwrite('compressed.tiff', image, 
                compression='lzw')

Advanced Features

Metadata Preservation

Images read with ImageIO retain metadata in the meta attribute:

image = imageio.imread('photo_with_exif.jpg')
print("EXIF data:", image.meta.get('exif', {}))
print("Image description:", image.meta.get('description', ''))

# Metadata varies by format:
# JPEG: exif, jfif, adobe, comment
# PNG: gamma, transparency, text chunks
# TIFF: extensive tag information

Data Type Handling

ImageIO preserves original data types and bit depths:

# 16-bit TIFF
image_16bit = imageio.imread('16bit_image.tiff')
print(f"Data type: {image_16bit.dtype}")  # e.g., uint16

# 32-bit float TIFF
float_image = imageio.imread('float_data.tiff')
print(f"Data type: {float_image.dtype}")  # e.g., float32

# Note: Unlike PIL, ImageIO preserves original bit depth

Error Handling

Common error scenarios and handling:

try:
    image = imageio.imread('nonexistent.jpg')
except FileNotFoundError:
    print("File not found")

try:
    image = imageio.imread('corrupted.jpg')
except Exception as e:
    print(f"Read error: {e}")

try:
    # Invalid image dimensions
    invalid_image = np.random.rand(100)  # 1D array
    imageio.imwrite('output.jpg', invalid_image)
except ValueError as e:
    print(f"Invalid image dimensions: {e}")

Install with Tessl CLI