0
# Format and Plugin Management
1

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

4
## Capabilities
5

6
### Format Documentation and Help
7

8
Get information about supported formats and their specific parameters.
9

10
```python { .api }
11
def help(name=None):
12
    """
13
    Print format documentation or list all formats.
14
    
15
    Parameters:
16
    - name (str, optional): 
17
        - Format name, file extension, or filename
18
        - If None, shows list of all available formats
19
    
20
    Returns:
21
    - None: Prints documentation to stdout
22
    """
23
```
24

25
**Usage Examples:**
26

27
```python
28
import imageio.v2 as imageio
29

30
# List all available formats
31
imageio.help()
32

33
# Get help for specific format
34
imageio.help('PNG')
35
imageio.help('JPEG')
36
imageio.help('TIFF')
37

38
# Get help by file extension
39
imageio.help('.gif')
40
imageio.help('.mp4')
41

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

46
# Get help for plugin-specific formats
47
imageio.help('DICOM')
48
imageio.help('FFmpeg')
49
imageio.help('FreeImage')
50
```
51

52
### Format Manager Access
53

54
Access the global format manager for advanced format control.
55

56
```python { .api }
57
# Global format manager instance
58
formats: FormatManager
59

60
# Convenient alias for formats.show()
61
show_formats: callable
62
```
63

64
**Usage Examples:**
65

66
```python
67
import imageio
68

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

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

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

82
# Check if format is available
83
format_names = ['PNG', 'JPEG', 'TIFF', 'GIF', 'DICOM']
84
for name in format_names:
85
    try:
86
        fmt = imageio.formats[name]
87
        print(f"✓ {name}: available")
88
    except KeyError:
89
        print(f"✗ {name}: not available")
90
```
91

92
## Plugin System
93

94
### Available Plugins
95

96
ImageIO supports numerous plugins for different file formats:
97

98
**Core Image Formats:**
99
- **pillow**: PIL/Pillow for common formats (JPEG, PNG, GIF, BMP, etc.)
100
- **pillowmulti**: Multi-image support via Pillow
101
- **freeimage**: FreeImage library for advanced formats
102
- **freeimagemulti**: Multi-image FreeImage support
103

104
**Scientific and Medical:**
105
- **dicom**: DICOM medical imaging format
106
- **fits**: FITS astronomical data format
107
- **simpleitk**: SimpleITK for medical imaging
108
- **tifffile**: Advanced TIFF support for scientific data
109

110
**Video and Animation:**
111
- **ffmpeg**: Video formats via FFmpeg
112
- **pyav**: Video support via PyAV library
113

114
**Specialized Formats:**
115
- **bsdf**: Binary Structured Data Format
116
- **feisem**: FEI-SEM microscopy format
117
- **lytro**: Lytro light field camera format
118
- **spe**: SPE spectrometer format
119
- **swf**: Adobe Flash format
120
- **rawpy**: RAW camera format support
121

122
**Utility Plugins:**
123
- **npz**: NumPy compressed array format
124
- **grab**: Screen capture functionality
125
- **example**: Template/example plugin
126

127
### Plugin Loading and Management
128

129
```python
130
import imageio
131

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

140
# Check plugin availability
141
plugin_names = ['pillow', 'ffmpeg', 'tifffile', 'dicom']
142
for plugin_name in plugin_names:
143
    try:
144
        plugin = getattr(imageio.plugins, plugin_name)
145
        print(f"✓ {plugin_name}: available")
146
    except AttributeError:
147
        print(f"✗ {plugin_name}: not available")
148
```
149

150
## Format Detection and Selection
151

152
### Automatic Format Detection
153

154
ImageIO automatically detects formats based on file extensions and content:
155

156
```python
157
import imageio.v2 as imageio
158

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

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

169
### Manual Format Control
170

171
Override automatic detection when needed:
172

173
```python
174
import imageio.v2 as imageio
175

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

180
# Modern v3 API style
181
import imageio.v3 as iio
182
image = iio.imread('data.raw', plugin='freeimage')
183
iio.imwrite('output.jpg', image, plugin='pillow')
184
```
185

186
## Configuration and Plugin Settings
187

188
### Plugin Configuration
189

190
Some plugins support configuration through environment variables or settings:
191

192
```python
193
import os
194
import imageio
195

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

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

207
# FreeImage plugin binary download
208
try:
209
    imageio.plugins.freeimage.download()
210
    print("FreeImage plugin ready")
211
except Exception as e:
212
    print(f"FreeImage setup failed: {e}")
213
```
214

215
### Configuration Access
216

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

219
```python { .api }
220
# Extension configuration
221
extension_list: List[str]  # List of all supported file extensions
222
known_extensions: Dict[str, dict]  # Extension to plugin mapping
223
video_extensions: List[str]  # Video-specific file extensions
224

225
# Plugin configuration  
226
known_plugins: Dict[str, str]  # Available plugin registry
227
PluginConfig: class  # Plugin configuration class
228
FileExtension: class  # File extension configuration class
229
```
230

231
**Usage Examples:**
232

233
```python
234
import imageio.config as config
235

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

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

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

249
# Get specific extension info
250
if '.tiff' in config.known_extensions:
251
    tiff_info = config.known_extensions['.tiff']
252
    print(f"TIFF extension info: {tiff_info}")
253
```
254

255
## Format-Specific Features
256

257
### JPEG Parameters
258

259
```python
260
import imageio.v2 as imageio
261
import numpy as np
262

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

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

269
# Get JPEG-specific help
270
imageio.help('JPEG')
271
```
272

273
### PNG Parameters
274

275
```python
276
# PNG compression and optimization
277
imageio.imwrite('compressed.png', image, compress_level=9)
278
imageio.imwrite('optimized.png', image, optimize=True)
279

280
# Get PNG-specific help
281
imageio.help('PNG')
282
```
283

284
### TIFF Parameters
285

286
```python
287
# TIFF compression options
288
imageio.imwrite('lzw_compressed.tiff', image, compression='lzw')
289
imageio.imwrite('jpeg_compressed.tiff', image, compression='jpeg')
290

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

295
# Get TIFF-specific help
296
imageio.help('TIFF')
297
```
298

299
### Video Format Parameters
300

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

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

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

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

314
# Get FFmpeg help
315
imageio.help('FFMPEG')
316
```
317

318
## Troubleshooting and Diagnostics
319

320
### Plugin Availability Check
321

322
```python
323
import imageio
324

325
def check_plugin_status():
326
    """Check status of key plugins."""
327
    
328
    plugins_to_check = {
329
        'pillow': 'Basic image formats (JPEG, PNG, GIF)',
330
        'ffmpeg': 'Video formats (MP4, AVI, MOV)',
331
        'tifffile': 'Advanced TIFF support',
332
        'dicom': 'Medical DICOM format',
333
        'freeimage': 'Extended format support'
334
    }
335
    
336
    print("Plugin Status Check:")
337
    print("-" * 50)
338
    
339
    for plugin_name, description in plugins_to_check.items():
340
        try:
341
            plugin = getattr(imageio.plugins, plugin_name)
342
            status = "✓ Available"
343
        except AttributeError:
344
            status = "✗ Not available"
345
        except Exception as e:
346
            status = f"⚠ Error: {e}"
347
        
348
        print(f"{plugin_name:12} | {status:15} | {description}")
349

350
# Run diagnostics
351
check_plugin_status()
352
```
353

354
### Format Support Testing
355

356
```python
357
def test_format_support(test_formats):
358
    """Test reading/writing support for various formats."""
359
    
360
    import numpy as np
361
    test_image = np.random.randint(0, 255, (50, 50, 3), dtype=np.uint8)
362
    
363
    print("Format Support Test:")
364
    print("-" * 40)
365
    
366
    for ext in test_formats:
367
        filename = f"test{ext}"
368
        
369
        try:
370
            # Test write
371
            imageio.imwrite(filename, test_image)
372
            
373
            # Test read
374
            read_image = imageio.imread(filename)
375
            
376
            # Clean up
377
            import os
378
            try:
379
                os.remove(filename)
380
            except:
381
                pass
382
            
383
            print(f"{ext:8} | ✓ Read/Write OK")
384
            
385
        except Exception as e:
386
            print(f"{ext:8} | ✗ Failed: {str(e)[:30]}...")
387

388
# Test common formats
389
test_formats = ['.jpg', '.png', '.tiff', '.bmp', '.gif']
390
test_format_support(test_formats)
391
```
392

393
### Getting Detailed Format Information
394

395
```python
396
def format_details(format_name):
397
    """Get detailed information about a specific format."""
398
    
399
    print(f"Format Details: {format_name}")
400
    print("=" * 40)
401
    
402
    try:
403
        # Get format help
404
        print("Documentation:")
405
        imageio.help(format_name)
406
        
407
        print("\nFormat object details:")
408
        fmt = imageio.formats[format_name]
409
        print(f"Format class: {type(fmt)}")
410
        print(f"Extensions: {getattr(fmt, 'extensions', 'Unknown')}")
411
        print(f"Description: {getattr(fmt, 'description', 'Unknown')}")
412
        
413
    except KeyError:
414
        print(f"Format '{format_name}' not found")
415
        print("Available formats:")
416
        imageio.show_formats()
417
    except Exception as e:
418
        print(f"Error getting format details: {e}")
419

420
# Get details for specific formats
421
format_details('PNG')
422
format_details('TIFF')
423
```