tessl/pypi-imageio

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

—

Pending

Overview

Eval results

Files

Format and Plugin Management

Name: tessl/pypi-imageio
Author: tessl

Tools for discovering available formats, getting format-specific help, and managing ImageIO's plugin system for different file formats.

Capabilities

Format Documentation and Help

Get information about supported formats and their specific parameters.

def help(name=None):
    """
    Print format documentation or list all formats.
    
    Parameters:
    - name (str, optional): 
        - Format name, file extension, or filename
        - If None, shows list of all available formats
    
    Returns:
    - None: Prints documentation to stdout
    """

Usage Examples:

import imageio.v2 as imageio

# List all available formats
imageio.help()

# Get help for specific format
imageio.help('PNG')
imageio.help('JPEG')
imageio.help('TIFF')

# Get help by file extension
imageio.help('.gif')
imageio.help('.mp4')

# Get help by filename (extension detected)
imageio.help('example.dicom')
imageio.help('animation.gif')

# Get help for plugin-specific formats
imageio.help('DICOM')
imageio.help('FFmpeg')
imageio.help('FreeImage')

Format Manager Access

Access the global format manager for advanced format control.

# Global format manager instance
formats: FormatManager

# Convenient alias for formats.show()
show_formats: callable

Usage Examples:

import imageio

# Show all formats (same as imageio.help())
imageio.show_formats()

# Access format manager directly
print(f"Format manager type: {type(imageio.formats)}")

# Get specific format by name
try:
    png_format = imageio.formats['PNG']
    print(f"PNG format: {png_format}")
except KeyError:
    print("PNG format not found")

# Check if format is available
format_names = ['PNG', 'JPEG', 'TIFF', 'GIF', 'DICOM']
for name in format_names:
    try:
        fmt = imageio.formats[name]
        print(f"✓ {name}: available")
    except KeyError:
        print(f"✗ {name}: not available")

Plugin System

Available Plugins

ImageIO supports numerous plugins for different file formats:

Core Image Formats:

pillow: PIL/Pillow for common formats (JPEG, PNG, GIF, BMP, etc.)
pillowmulti: Multi-image support via Pillow
freeimage: FreeImage library for advanced formats
freeimagemulti: Multi-image FreeImage support

Scientific and Medical:

dicom: DICOM medical imaging format
fits: FITS astronomical data format
simpleitk: SimpleITK for medical imaging
tifffile: Advanced TIFF support for scientific data

Video and Animation:

ffmpeg: Video formats via FFmpeg
pyav: Video support via PyAV library

Specialized Formats:

bsdf: Binary Structured Data Format
feisem: FEI-SEM microscopy format
lytro: Lytro light field camera format
spe: SPE spectrometer format
swf: Adobe Flash format
rawpy: RAW camera format support

Utility Plugins:

npz: NumPy compressed array format
grab: Screen capture functionality
example: Template/example plugin

Plugin Loading and Management

import imageio

# Plugins are loaded dynamically when accessed
# Access plugin modules directly
try:
    pillow_plugin = imageio.plugins.pillow
    print(f"Pillow plugin loaded: {pillow_plugin}")
except AttributeError as e:
    print(f"Plugin not available: {e}")

# Check plugin availability
plugin_names = ['pillow', 'ffmpeg', 'tifffile', 'dicom']
for plugin_name in plugin_names:
    try:
        plugin = getattr(imageio.plugins, plugin_name)
        print(f"✓ {plugin_name}: available")
    except AttributeError:
        print(f"✗ {plugin_name}: not available")

Format Detection and Selection

Automatic Format Detection

ImageIO automatically detects formats based on file extensions and content:

import imageio.v2 as imageio

# Format auto-detection by extension
image_jpg = imageio.imread('photo.jpg')      # Uses JPEG plugin
image_png = imageio.imread('diagram.png')    # Uses PNG plugin  
image_tif = imageio.imread('data.tiff')      # Uses TIFF plugin
volume_dcm = imageio.volread('scan.dcm')     # Uses DICOM plugin

# Format detection by content (when extension is ambiguous)
image_unknown = imageio.imread('file_without_extension')  # Detects by magic bytes

Manual Format Control

Override automatic detection when needed:

import imageio.v2 as imageio

# Force specific format (v2 API style)
image = imageio.imread('data.raw', format='RAW-FI')
imageio.imwrite('output.jpg', image, format='JPEG-PIL')

# Modern v3 API style
import imageio.v3 as iio
image = iio.imread('data.raw', plugin='freeimage')
iio.imwrite('output.jpg', image, plugin='pillow')

Configuration and Plugin Settings

Plugin Configuration

Some plugins support configuration through environment variables or settings:

import os
import imageio

# FFmpeg plugin configuration (example)
# Set FFmpeg binary path if not in system PATH
# os.environ['IMAGEIO_FFMPEG_EXE'] = '/path/to/ffmpeg'

# Check if FFmpeg is available
try:
    imageio.plugins.ffmpeg.download()  # Download if needed
    print("FFmpeg plugin ready")
except Exception as e:
    print(f"FFmpeg setup failed: {e}")

# FreeImage plugin binary download
try:
    imageio.plugins.freeimage.download()
    print("FreeImage plugin ready")
except Exception as e:
    print(f"FreeImage setup failed: {e}")

Configuration Access

Access ImageIO's configuration information about file extensions, plugins, and format mappings.

# Extension configuration
extension_list: List[str]  # List of all supported file extensions
known_extensions: Dict[str, dict]  # Extension to plugin mapping
video_extensions: List[str]  # Video-specific file extensions

# Plugin configuration  
known_plugins: Dict[str, str]  # Available plugin registry
PluginConfig: class  # Plugin configuration class
FileExtension: class  # File extension configuration class

Usage Examples:

import imageio.config as config

# Get known file extensions
extensions = config.extension_list
print(f"Supported extensions: {len(extensions)}")
print(f"Sample extensions: {extensions[:10]}")

# Get known plugins
plugins = config.known_plugins
print(f"Available plugins: {list(plugins.keys())}")

# Check video extensions specifically
video_exts = config.video_extensions
print(f"Video extensions: {video_exts}")

# Get specific extension info
if '.tiff' in config.known_extensions:
    tiff_info = config.known_extensions['.tiff']
    print(f"TIFF extension info: {tiff_info}")

Format-Specific Features

JPEG Parameters

import imageio.v2 as imageio
import numpy as np

image = np.random.randint(0, 255, (200, 200, 3), dtype=np.uint8)

# JPEG quality and optimization
imageio.imwrite('high_quality.jpg', image, quality=95, optimize=True)
imageio.imwrite('progressive.jpg', image, quality=85, progressive=True)

# Get JPEG-specific help
imageio.help('JPEG')

PNG Parameters

# PNG compression and optimization
imageio.imwrite('compressed.png', image, compress_level=9)
imageio.imwrite('optimized.png', image, optimize=True)

# Get PNG-specific help
imageio.help('PNG')

TIFF Parameters

# TIFF compression options
imageio.imwrite('lzw_compressed.tiff', image, compression='lzw')
imageio.imwrite('jpeg_compressed.tiff', image, compression='jpeg')

# Multi-page TIFF
images = [np.random.randint(0, 255, (100, 100), dtype=np.uint8) for _ in range(5)]
imageio.mimwrite('multipage.tiff', images, compression='lzw')

# Get TIFF-specific help
imageio.help('TIFF')

Video Format Parameters

# FFmpeg video parameters
frames = [np.random.randint(0, 255, (240, 320, 3), dtype=np.uint8) for _ in range(100)]

# Basic MP4
imageio.mimwrite('basic.mp4', frames, fps=30)

# High-quality MP4 with custom codec
imageio.mimwrite('hq.mp4', frames, fps=60, codec='libx264', quality=8)

# Custom bitrate and preset
imageio.mimwrite('custom.mp4', frames, fps=30, bitrate='2M', preset='slow')

# Get FFmpeg help
imageio.help('FFMPEG')

Troubleshooting and Diagnostics

Plugin Availability Check

import imageio

def check_plugin_status():
    """Check status of key plugins."""
    
    plugins_to_check = {
        'pillow': 'Basic image formats (JPEG, PNG, GIF)',
        'ffmpeg': 'Video formats (MP4, AVI, MOV)',
        'tifffile': 'Advanced TIFF support',
        'dicom': 'Medical DICOM format',
        'freeimage': 'Extended format support'
    }
    
    print("Plugin Status Check:")
    print("-" * 50)
    
    for plugin_name, description in plugins_to_check.items():
        try:
            plugin = getattr(imageio.plugins, plugin_name)
            status = "✓ Available"
        except AttributeError:
            status = "✗ Not available"
        except Exception as e:
            status = f"⚠ Error: {e}"
        
        print(f"{plugin_name:12} | {status:15} | {description}")

# Run diagnostics
check_plugin_status()

Format Support Testing

def test_format_support(test_formats):
    """Test reading/writing support for various formats."""
    
    import numpy as np
    test_image = np.random.randint(0, 255, (50, 50, 3), dtype=np.uint8)
    
    print("Format Support Test:")
    print("-" * 40)
    
    for ext in test_formats:
        filename = f"test{ext}"
        
        try:
            # Test write
            imageio.imwrite(filename, test_image)
            
            # Test read
            read_image = imageio.imread(filename)
            
            # Clean up
            import os
            try:
                os.remove(filename)
            except:
                pass
            
            print(f"{ext:8} | ✓ Read/Write OK")
            
        except Exception as e:
            print(f"{ext:8} | ✗ Failed: {str(e)[:30]}...")

# Test common formats
test_formats = ['.jpg', '.png', '.tiff', '.bmp', '.gif']
test_format_support(test_formats)

Getting Detailed Format Information

def format_details(format_name):
    """Get detailed information about a specific format."""
    
    print(f"Format Details: {format_name}")
    print("=" * 40)
    
    try:
        # Get format help
        print("Documentation:")
        imageio.help(format_name)
        
        print("\nFormat object details:")
        fmt = imageio.formats[format_name]
        print(f"Format class: {type(fmt)}")
        print(f"Extensions: {getattr(fmt, 'extensions', 'Unknown')}")
        print(f"Description: {getattr(fmt, 'description', 'Unknown')}")
        
    except KeyError:
        print(f"Format '{format_name}' not found")
        print("Available formats:")
        imageio.show_formats()
    except Exception as e:
        print(f"Error getting format details: {e}")

# Get details for specific formats
format_details('PNG')
format_details('TIFF')

Install with Tessl CLI