0
# ImageIO
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: imageio
7
- **Type**: Image Processing Library
8
- **Language**: Python
9
- **Installation**: `pip install imageio`
10
- **Dependencies**: numpy, pillow >= 8.3.2
11
12
## Core Imports
13
14
```python
15
import imageio
16
```
17
18
Common usage patterns:
19
20
```python
21
# v2 API (current stable)
22
import imageio.v2 as imageio
23
24
# v3 API (modern interface)
25
import imageio.v3 as iio
26
```
27
28
## Basic Usage
29
30
```python
31
import imageio.v2 as imageio
32
import numpy as np
33
34
# Read a single image
35
image = imageio.imread('path/to/image.jpg')
36
print(f"Image shape: {image.shape}")
37
38
# Write a single image
39
imageio.imwrite('output.png', image)
40
41
# Read multiple images (like GIF frames)
42
images = imageio.mimread('animation.gif')
43
print(f"Number of frames: {len(images)}")
44
45
# Write multiple images as GIF
46
imageio.mimwrite('output.gif', images, duration=0.5)
47
48
# Read volume data (3D medical/scientific)
49
volume = imageio.volread('scan.tiff')
50
print(f"Volume shape: {volume.shape}")
51
52
# Modern v3 API example
53
import imageio.v3 as iio
54
55
# Read with explicit control
56
image = iio.imread('image.jpg', index=0)
57
58
# Iterate through images in a file
59
for frame in iio.imiter('animation.gif'):
60
print(f"Frame shape: {frame.shape}")
61
62
# Get image properties without loading pixel data
63
props = iio.improps('image.jpg')
64
print(f"Shape: {props.shape}, dtype: {props.dtype}")
65
```
66
67
## Architecture
68
69
ImageIO uses a plugin-based architecture that provides format flexibility:
70
71
- **Format Plugins**: 20+ specialized plugins for different file formats (DICOM, TIFF, FFmpeg, PIL, etc.)
72
- **Legacy v2 API**: Backward-compatible interface with explicit data type handling (images, volumes)
73
- **Modern v3 API**: Streamlined interface with unified resource handling and context managers
74
- **Plugin Management**: Automatic format detection with manual override capabilities
75
- **Resource Abstraction**: Supports files, URLs, bytes, file objects, and pathlib.Path
76
77
This design enables ImageIO to handle diverse formats while providing consistent APIs for scientific computing, computer vision, and multimedia applications.
78
79
## Capabilities
80
81
### Module Imports
82
83
Direct access to ImageIO's API versions and configuration modules for advanced usage and customization.
84
85
```python { .api }
86
# API version modules
87
import imageio.v2 # Legacy v2 API
88
import imageio.v3 # Modern v3 API
89
90
# Configuration and plugin access
91
import imageio.config # Plugin and format configuration
92
import imageio.plugins # Plugin registry and implementations
93
```
94
95
### Image I/O Operations
96
97
Core functionality for reading and writing single images, supporting all major image formats with automatic format detection and metadata preservation.
98
99
```python { .api }
100
def imread(uri, format=None, **kwargs):
101
"""Read a single image from file, URL, or bytes."""
102
103
def imwrite(uri, im, format=None, **kwargs):
104
"""Write a single image to file or return as bytes."""
105
```
106
107
[Image I/O Operations](./image-io.md)
108
109
### Multi-Image Operations
110
111
Handle sequences of images like GIF animations, TIFF stacks, or video frames with memory management and batch processing capabilities.
112
113
```python { .api }
114
def mimread(uri, format=None, memtest="256MB", **kwargs):
115
"""Read multiple images with memory protection."""
116
117
def mimwrite(uri, ims, format=None, **kwargs):
118
"""Write multiple images as animation or stack."""
119
```
120
121
[Multi-Image Operations](./multi-image.md)
122
123
### Volume Data Handling
124
125
Support for 3D volumetric data commonly used in medical imaging, scientific visualization, and microscopy applications.
126
127
```python { .api }
128
def volread(uri, format=None, **kwargs):
129
"""Read 3D volume data (NxMxL arrays)."""
130
131
def volwrite(uri, vol, format=None, **kwargs):
132
"""Write 3D volume data to file."""
133
134
def mvolread(uri, format=None, memtest="1GB", **kwargs):
135
"""Read multiple volumes with memory protection."""
136
137
def mvolwrite(uri, vols, format=None, **kwargs):
138
"""Write multiple volumes to file."""
139
```
140
141
[Volume Data Handling](./volume-data.md)
142
143
### Modern v3 API
144
145
Streamlined interface with context managers, unified resource handling, and enhanced metadata access for modern Python development.
146
147
```python { .api }
148
def imopen(uri, io_mode, **kwargs):
149
"""Open image resource as context manager."""
150
151
def imiter(uri, **kwargs):
152
"""Iterate over images in a file."""
153
154
def improps(uri, **kwargs):
155
"""Get standardized image properties."""
156
157
def immeta(uri, **kwargs):
158
"""Get format-specific metadata."""
159
```
160
161
[Modern v3 API](./v3-api.md)
162
163
### Reader/Writer Objects
164
165
Low-level interfaces for manual control over reading and writing operations with fine-grained parameter access.
166
167
```python { .api }
168
def get_reader(uri, format=None, mode="?", **kwargs):
169
"""Get reader object for manual reading."""
170
171
def get_writer(uri, format=None, mode="?", **kwargs):
172
"""Get writer object for manual writing."""
173
```
174
175
[Reader/Writer Objects](./reader-writer.md)
176
177
### Format and Plugin Management
178
179
Tools for discovering available formats, getting format-specific help, and managing the plugin system.
180
181
```python { .api }
182
def help(name=None):
183
"""Show format documentation or list formats."""
184
185
# Format manager access
186
formats: FormatManager
187
show_formats: callable
188
```
189
190
[Format and Plugin Management](./formats-plugins.md)
191
192
## Types
193
194
```python { .api }
195
# Type aliases for input/output
196
ImageResource = Union[str, bytes, BytesIO, Path, BinaryIO]
197
ArrayLike = Union[np.ndarray, list, tuple]
198
199
# Core array type with metadata
200
class Array(np.ndarray):
201
"""NumPy array with attached metadata dictionary."""
202
meta: dict
203
204
# V3 standardized properties
205
@dataclass
206
class ImageProperties:
207
shape: Tuple[int, ...]
208
dtype: np.dtype
209
n_images: Optional[int] = None
210
is_batch: bool = False
211
spacing: Optional[tuple] = None
212
213
# Format management
214
class FormatManager:
215
"""Registry and manager for format plugins."""
216
def show(self) -> None: ...
217
def __getitem__(self, name: str) -> Format: ...
218
219
class Format:
220
"""Base class for format plugins."""
221
class Reader: ...
222
class Writer: ...
223
224
# Plugin base classes
225
class PluginV3:
226
"""Base class for v3 plugins."""
227
def read(self, **kwargs) -> np.ndarray: ...
228
def write(self, image: ArrayLike, **kwargs): ...
229
def properties(self, **kwargs) -> ImageProperties: ...
230
def metadata(self, **kwargs) -> dict: ...
231
232
# Constants
233
RETURN_BYTES: str # Special URI for returning bytes
234
```