0
# PyVips
1

2
PyVips is a Python binding for the libvips image processing library that provides high-performance image manipulation capabilities through a streaming, pipeline-based architecture. It enables developers to perform complex image processing operations including format conversion, resizing, filtering, color space transformations, and advanced effects while maintaining memory efficiency by processing images in sections rather than loading them entirely into memory.
3

4
## Package Information
5

6
- **Package Name**: pyvips
7
- **Language**: Python
8
- **Installation**: `pip install pyvips`
9
- **Binary Mode**: Automatically uses compiled binary extensions when available for maximum performance, falls back to ABI mode for broader compatibility
10

11
## Core Imports
12

13
```python
14
import pyvips
15
```
16

17
For most image operations, you'll primarily work with the Image class:
18

19
```python
20
from pyvips import Image
21
```
22

23
Additional imports for specific functionality:
24

25
```python
26
from pyvips import (
27
    Image, Source, Target, SourceCustom, TargetCustom,
28
    Error, Operation, Interpolate, Region
29
)
30
```
31

32
## Basic Usage
33

34
```python
35
import pyvips
36

37
# Load an image
38
image = pyvips.Image.new_from_file('input.jpg')
39

40
# Basic operations - these return new Image objects  
41
resized = image.resize(0.5)  # Resize to 50%
42
rotated = image.rotate(90)   # Rotate 90 degrees
43
converted = image.colourspace('srgb')  # Convert color space
44

45
# Chain operations for efficiency
46
processed = (image
47
    .resize(0.5)
48
    .rotate(90) 
49
    .gaussblur(1.5)
50
    .sharpen())
51

52
# Save result
53
processed.write_to_file('output.jpg')
54

55
# Memory-efficient processing from buffer
56
data = open('input.jpg', 'rb').read()
57
image = pyvips.Image.new_from_buffer(data, '')
58
result = image.thumbnail_image(200)
59
output_data = result.write_to_buffer('.jpg', Q=95)
60
```
61

62
## Architecture
63

64
PyVips implements a streaming, pipeline-based architecture that provides superior performance and memory efficiency:
65

66
- **Image Objects**: Immutable image representations that describe processing pipelines rather than storing pixel data
67
- **Lazy Evaluation**: Operations are queued and executed only when pixel data is actually needed
68
- **Streaming Processing**: Images are processed in small tiles, keeping memory usage constant regardless of image size
69
- **Operation Pipeline**: Each operation creates a new Image object representing the cumulative pipeline
70
- **Automatic Optimization**: libvips automatically optimizes operation chains for maximum efficiency
71

72
This design enables processing of very large images (gigapixel+) with minimal memory usage while maintaining high performance through parallel processing and efficient caching.
73

74
## Capabilities
75

76
### Image Loading and Creation
77

78
Primary methods for creating Image objects from various sources including files, memory buffers, arrays, and custom sources. Supports all major image formats and provides flexible initialization options.
79

80
```python { .api }
81
@classmethod
82
def new_from_file(cls, vips_filename: str, **kwargs) -> 'Image': ...
83

84
@classmethod  
85
def new_from_buffer(cls, data: bytes, options: str, **kwargs) -> 'Image': ...
86

87
@classmethod
88
def new_from_array(cls, array, scale: float = 1.0, offset: float = 0.0, 
89
                   interpretation: str = None) -> 'Image': ...
90

91
@classmethod
92
def new_from_memory(cls, data: bytes, width: int, height: int, 
93
                    bands: int, format: str) -> 'Image': ...
94
```
95

96
[Image Creation](./image-creation.md)
97

98
### Image Operations and Processing
99

100
Comprehensive image processing operations including geometric transformations, filtering, color manipulation, and advanced effects. PyVips dynamically exposes hundreds of libvips operations as Image methods through metaclass magic. All operations support method chaining and return new Image objects.
101

102
```python { .api }
103
def resize(self, scale: float, **kwargs) -> 'Image': ...
104
def rotate(self, angle: float, **kwargs) -> 'Image': ...
105
def gaussblur(self, sigma: float, **kwargs) -> 'Image': ...
106
def sharpen(self, **kwargs) -> 'Image': ...
107
def colourspace(self, space: str, **kwargs) -> 'Image': ...
108
def thumbnail_image(self, width: int, **kwargs) -> 'Image': ...
109
```
110

111
[Image Operations](./image-operations.md)
112

113
### Image Output and Export
114

115
Methods for saving and exporting images to files, memory buffers, and custom targets. Supports all major output formats with extensive format-specific options.
116

117
```python { .api }
118
def write_to_file(self, vips_filename: str, **kwargs) -> None: ...
119
def write_to_buffer(self, format_string: str, **kwargs) -> bytes: ...
120
def write_to_target(self, target: 'Target', format_string: str, **kwargs) -> None: ...
121
def write_to_memory(self) -> bytes: ...
122
```
123

124
[Image Output](./image-output.md)
125

126
### I/O Connections and Streaming
127

128
Advanced I/O system supporting custom sources and targets for streaming operations, enabling integration with various data sources and destinations beyond the filesystem.
129

130
```python { .api }
131
class Source:
132
    @classmethod
133
    def new_from_file(cls, filename: str) -> 'Source': ...
134
    
135
    @classmethod  
136
    def new_from_memory(cls, data: bytes) -> 'Source': ...
137

138
class Target:
139
    @classmethod
140
    def new_to_file(cls, filename: str) -> 'Target': ...
141
    
142
    @classmethod
143
    def new_to_memory(cls) -> 'Target': ...
144
```
145

146
[I/O Connections](./io-connections.md)
147

148
### Image Properties and Metadata
149

150
Access and manipulation of image properties, metadata, and introspection capabilities for understanding image characteristics and processing pipelines.
151

152
```python { .api }
153
def get(self, name: str): ...
154
def set(self, name: str, value) -> None: ...
155
def get_fields(self) -> list: ...
156
def remove(self, name: str) -> None: ...
157

158
# Properties
159
@property
160
def width(self) -> int: ...
161

162
@property  
163
def height(self) -> int: ...
164

165
@property
166
def bands(self) -> int: ...
167

168
@property
169
def format(self) -> str: ...
170
```
171

172
[Properties and Metadata](./properties-metadata.md)
173

174
### Array and NumPy Integration
175

176
Seamless integration with Python arrays and NumPy for data exchange, enabling easy interoperability with the scientific Python ecosystem.
177

178
```python { .api }
179
def tolist(self) -> list: ...
180
def numpy(self, dtype=None): ...
181
def __array__(self, dtype=None): ...
182

183
@classmethod
184
def new_from_list(cls, array: list, scale: float = 1.0, 
185
                  offset: float = 0.0) -> 'Image': ...
186
```
187

188
[Array Integration](./array-integration.md)
189

190
### Low-Level Operations and System Control
191

192
Advanced functionality for operation introspection, cache management, and low-level system control for fine-tuning performance and behavior.
193

194
```python { .api }
195
class Operation:
196
    @classmethod
197
    def call(cls, operation_name: str, *args, **kwargs): ...
198
    
199
    @classmethod
200
    def generate_docstring(cls, operation_name: str) -> str: ...
201

202
def cache_set_max(mx: int) -> None: ...
203
def cache_set_max_mem(mx: int) -> None: ...
204
def version(flag: int) -> int: ...
205
```
206

207
[System Control](./system-control.md)
208

209
### Enumerations and Constants
210

211
Comprehensive set of enumeration classes defining constants for all image processing operations, formats, and options.
212

213
```python { .api }
214
class BandFormat:
215
    UCHAR: str
216
    CHAR: str  
217
    USHORT: str
218
    SHORT: str
219
    UINT: str
220
    INT: str
221
    FLOAT: str
222
    COMPLEX: str
223
    DOUBLE: str
224
    DPCOMPLEX: str
225

226
class Interpretation:
227
    MULTIBAND: str
228
    B_W: str
229
    HISTOGRAM: str
230
    XYZ: str
231
    LAB: str
232
    CMYK: str
233
    RGB: str
234
    SRGB: str
235
```
236

237
[Enumerations](./enumerations.md)
238

239
## Error Handling
240

241
```python { .api }
242
class Error(Exception):
243
    """An error from vips."""
244
    message: str
245
    detail: str
246
```
247

248
PyVips operations can raise `pyvips.Error` exceptions. The error contains both a high-level message and detailed diagnostics from the underlying libvips library.
249

250
## Types
251

252
```python { .api }
253
class Image:
254
    """Main image class wrapping VipsImage."""
255
    
256
    width: int
257
    height: int  
258
    bands: int
259
    format: str
260
    interpretation: str
261
    xres: float
262
    yres: float
263
    
264
class Source:
265
    """Input connection for streaming."""
266
    
267
class Target:  
268
    """Output connection for streaming."""
269
    
270
class SourceCustom(Source):
271
    """Custom input source."""
272
    
273
class TargetCustom(Target):
274
    """Custom output target."""
275
    
276
class Operation:
277
    """libvips operation wrapper."""
278
    
279
class Interpolate:
280
    """Interpolation method."""
281
    
282
class Region:
283
    """Region of an image for pixel access."""
284
```