0
# Image Creation
1

2
Methods for creating Image objects from various sources including files, memory buffers, arrays, and custom sources. PyVips supports all major image formats and provides flexible initialization options for different use cases.
3

4
## Capabilities
5

6
### File Loading
7

8
Load images from filesystem paths with automatic format detection and extensive format-specific options.
9

10
```python { .api }
11
@classmethod
12
def new_from_file(cls, vips_filename: str, **kwargs) -> 'Image':
13
    """
14
    Load an image from a file.
15
    
16
    Parameters:
17
    - vips_filename: str, file path to load
18
    - access: str, access pattern ('random', 'sequential', 'sequential_unbuffered')  
19
    - fail_on: str, error level ('none', 'truncated', 'error', 'warning')
20
    - disc: bool, force disk-based processing
21
    - Format-specific options like 'page' for multi-page formats, 'dpi' for PDF, etc.
22
    
23
    Returns:
24
    Image object
25
    """
26
```
27

28
Example usage:
29

30
```python
31
# Basic file loading
32
image = pyvips.Image.new_from_file('photo.jpg')
33

34
# Load with sequential access for large files
35
image = pyvips.Image.new_from_file('large.tiff', access='sequential')
36

37
# Load specific page from multi-page format
38
image = pyvips.Image.new_from_file('document.pdf', page=2, dpi=300)
39

40
# Load with error handling control
41
image = pyvips.Image.new_from_file('input.jpg', fail_on='warning')
42
```
43

44
### Buffer Loading
45

46
Load images from memory buffers, useful for processing images received from network requests or other in-memory sources.
47

48
```python { .api }
49
@classmethod  
50
def new_from_buffer(cls, data: bytes, options: str, **kwargs) -> 'Image':
51
    """
52
    Load an image from a memory buffer.
53
    
54
    Parameters:
55
    - data: bytes, image data in memory
56
    - options: str, format hint (empty string for auto-detection)
57
    - Same keyword arguments as new_from_file
58
    
59
    Returns:
60
    Image object
61
    """
62
```
63

64
Example usage:
65

66
```python
67
# Load from HTTP response
68
import requests
69
response = requests.get('https://example.com/image.jpg')
70
image = pyvips.Image.new_from_buffer(response.content, '')
71

72
# Load with format hint
73
with open('image.webp', 'rb') as f:
74
    data = f.read()
75
image = pyvips.Image.new_from_buffer(data, '.webp')
76

77
# Load with specific options
78
image = pyvips.Image.new_from_buffer(jpeg_data, '.jpg', shrink=2)
79
```
80

81
### Array Creation
82

83
Create images from Python lists and arrays, enabling programmatic image generation and integration with numerical data.
84

85
```python { .api }
86
@classmethod
87
def new_from_array(cls, array, scale: float = 1.0, offset: float = 0.0, 
88
                   interpretation: str = None) -> 'Image':
89
    """
90
    Create an image from a 2D array.
91
    
92
    Parameters:
93
    - array: 2D list/array of numbers, image pixel data
94
    - scale: float, scale factor applied to pixel values
95
    - offset: float, offset added to pixel values  
96
    - interpretation: str, color space interpretation
97
    
98
    Returns:
99
    Image object
100
    """
101

102
@classmethod
103
def new_from_list(cls, array: list, scale: float = 1.0, 
104
                  offset: float = 0.0) -> 'Image':
105
    """
106
    Create an image from a Python list.
107
    
108
    Parameters:
109
    - array: 2D list of numbers
110
    - scale: float, scale factor
111
    - offset: float, offset value
112
    
113
    Returns:
114
    Image object
115
    """
116
```
117

118
Example usage:
119

120
```python
121
# Create from 2D list
122
pixel_data = [
123
    [255, 128, 0],
124
    [128, 255, 128], 
125
    [0, 128, 255]
126
]
127
image = pyvips.Image.new_from_array(pixel_data)
128

129
# Create with scaling
130
kernel = [
131
    [-1, -1, -1],
132
    [-1,  8, -1],
133
    [-1, -1, -1]
134
]
135
sharpen_kernel = pyvips.Image.new_from_array(kernel, scale=1, offset=0)
136

137
# Create with color space
138
rgb_data = [[255, 0, 0], [0, 255, 0], [0, 0, 255]]
139
image = pyvips.Image.new_from_array(rgb_data, interpretation='srgb')
140
```
141

142
### Raw Memory Creation
143

144
Create images from raw pixel data in memory, useful for interfacing with other image processing libraries or hardware.
145

146
```python { .api }
147
@classmethod
148
def new_from_memory(cls, data: bytes, width: int, height: int, 
149
                    bands: int, format: str) -> 'Image':
150
    """
151
    Create an image from raw memory data.
152
    
153
    Parameters:
154
    - data: bytes, raw pixel data
155
    - width: int, image width in pixels
156
    - height: int, image height in pixels  
157
    - bands: int, number of bands (channels)
158
    - format: str, pixel format ('uchar', 'ushort', 'float', etc.)
159
    
160
    Returns:
161
    Image object
162
    """
163
```
164

165
Example usage:
166

167
```python
168
# Create from raw RGB data
169
width, height = 100, 100
170
bands = 3
171
pixel_data = bytes([255, 0, 0] * (width * height))  # Red image
172
image = pyvips.Image.new_from_memory(pixel_data, width, height, bands, 'uchar')
173

174
# Create from float data  
175
import struct
176
float_data = struct.pack('f' * (width * height), *([0.5] * (width * height)))
177
image = pyvips.Image.new_from_memory(float_data, width, height, 1, 'float')
178
```
179

180
### Source-based Loading
181

182
Load images from Source objects for advanced I/O scenarios and streaming operations.
183

184
```python { .api }
185
@classmethod
186
def new_from_source(cls, source: 'Source', options: str, **kwargs) -> 'Image':
187
    """
188
    Load an image from a Source object.
189
    
190
    Parameters:
191
    - source: Source object providing the image data
192
    - options: str, format hint
193
    - Same keyword arguments as new_from_file
194
    
195
    Returns:
196
    Image object
197
    """
198
```
199

200
Example usage:
201

202
```python
203
# Load from file source
204
source = pyvips.Source.new_from_file('image.jpg')
205
image = pyvips.Image.new_from_source(source, '')
206

207
# Load from memory source
208
data = open('image.png', 'rb').read()  
209
source = pyvips.Source.new_from_memory(data)
210
image = pyvips.Image.new_from_source(source, '.png')
211

212
# Load from custom source
213
custom_source = pyvips.SourceCustom()
214
custom_source.on_read(my_read_handler)
215
image = pyvips.Image.new_from_source(custom_source, '')
216
```
217

218
### Temporary File Creation
219

220
Create temporary image files for intermediate processing steps.
221

222
```python { .api }
223
@classmethod
224
def new_temp_file(cls, format: str) -> 'Image':
225
    """
226
    Create a temporary file image.
227
    
228
    Parameters:
229
    - format: str, file format suffix (e.g., '.jpg', '.png')
230
    
231
    Returns:
232
    Image object representing temporary file
233
    """
234
```
235

236
Example usage:
237

238
```python
239
# Create temporary JPEG
240
temp_image = pyvips.Image.new_temp_file('.jpg')
241

242
# Use for intermediate processing
243
large_image = pyvips.Image.new_from_file('huge.tiff')
244
temp = large_image.thumbnail_image(1000).new_temp_file('.jpg')
245
result = temp.gaussblur(2.0)
246
```
247

248
## Format Support
249

250
PyVips automatically detects formats and supports extensive format-specific options:
251

252
### Common Formats
253
- **JPEG**: quality, optimize, strip, etc.
254
- **PNG**: compression, palette, etc.  
255
- **TIFF**: compression, tile, pyramid, etc.
256
- **WebP**: quality, lossless, alpha_q, etc.
257
- **HEIF/AVIF**: quality, compression, speed, etc.
258

259
### Specialized Formats  
260
- **OpenSlide**: Multi-resolution microscopy images
261
- **OpenEXR**: High dynamic range images
262
- **FITS**: Astronomical images
263
- **Matlab**: .mat files
264
- **Raw formats**: Various camera raw formats
265

266
### Multi-page Support
267
- **PDF**: page, dpi, background
268
- **TIFF**: page, n (number of pages)
269
- **GIF**: page, n
270
- **WebP**: page, n
271

272
## Error Handling
273

274
Image creation operations can fail for various reasons:
275

276
```python
277
try:
278
    image = pyvips.Image.new_from_file('nonexistent.jpg')
279
except pyvips.Error as e:
280
    print(f"Failed to load image: {e.message}")
281
    print(f"Details: {e.details}")
282

283
# Check file existence first
284
import os
285
if os.path.exists(filename):
286
    image = pyvips.Image.new_from_file(filename)
287
else:
288
    print("File not found")
289
```