0
# Image Classes
1

2
Main container and image classes for handling HEIF/AVIF data. These classes provide comprehensive access to image data, metadata, and specialized image types including depth images and auxiliary images.
3

4
## Capabilities
5

6
### HeifFile - Image Container
7

8
Main container class for HEIF/AVIF files that can contain one or more images with metadata. Provides both container-like access and direct access to the primary image.
9

10
```python { .api }
11
class HeifFile:
12
    """
13
    Container for HEIF/AVIF images with metadata support.
14
    
15
    Properties:
16
    - size: tuple[int, int], dimensions of primary image (width, height)
17
    - mode: str, color mode ('RGB', 'RGBA', 'L', etc.)
18
    - data: bytes, raw image data of primary image
19
    - stride: int, bytes per row of primary image
20
    - info: dict, metadata dictionary with EXIF, XMP, IPTC data
21
    - mimetype: str, MIME type of file ('image/heif' or 'image/avif')
22
    - primary_index: int, index of primary image in multi-image file
23
    - has_alpha: bool, True if primary image has alpha channel
24
    - premultiplied_alpha: bool, True if alpha is premultiplied
25
    """
26
    
27
    def __init__(self, fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs):
28
        """
29
        Initialize HeifFile from file path or file-like object.
30
        
31
        Parameters:
32
        - fp: file path (str) or file-like object
33
        - convert_hdr_to_8bit: bool, convert HDR to 8-bit
34
        - bgr_mode: bool, use BGR pixel order
35
        - **kwargs: additional decoding options
36
        """
37
    
38
    @property
39
    def size(self) -> tuple[int, int]:
40
        """Dimensions of primary image (width, height)."""
41
    
42
    @property
43
    def mode(self) -> str:
44
        """Color mode of primary image ('RGB', 'RGBA', 'L', etc.)."""
45
    
46
    @property
47
    def data(self) -> bytes:
48
        """Raw image data of primary image."""
49
    
50
    @property
51
    def stride(self) -> int:
52
        """Bytes per row of primary image."""
53
    
54
    @property
55
    def info(self) -> dict:
56
        """Metadata dictionary with EXIF, XMP, IPTC data."""
57
    
58
    @property
59
    def mimetype(self) -> str:
60
        """MIME type of file ('image/heif' or 'image/avif')."""
61
    
62
    @property
63
    def primary_index(self) -> int:
64
        """Index of primary image in multi-image file."""
65
    
66
    @property
67
    def has_alpha(self) -> bool:
68
        """True if primary image has alpha channel."""
69
    
70
    @property
71
    def premultiplied_alpha(self) -> bool:
72
        """True if alpha is premultiplied."""
73
    
74
    @premultiplied_alpha.setter
75
    def premultiplied_alpha(self, value: bool):
76
        """Set premultiplied alpha state."""
77
    
78
    @property
79
    def __array_interface__(self):
80
        """NumPy array interface for direct array access."""
81
    
82
    def save(self, fp, **kwargs):
83
        """
84
        Save all images to HEIF/AVIF file.
85
        
86
        Parameters:
87
        - fp: output file path or file-like object
88
        - **kwargs: encoding options (quality, etc.)
89
        """
90
    
91
    def add_frombytes(self, mode, size, data, **kwargs):
92
        """
93
        Add image from raw bytes data.
94
        
95
        Parameters:
96
        - mode: str, color mode ('RGB', 'RGBA', etc.)
97
        - size: tuple[int, int], image dimensions
98
        - data: bytes, raw image data
99
        - **kwargs: additional options
100
        """
101
    
102
    def add_from_heif(self, image):
103
        """
104
        Add image from another HeifImage.
105
        
106
        Parameters:
107
        - image: HeifImage, source image to add
108
        """
109
    
110
    def add_from_pillow(self, image):
111
        """
112
        Add image from Pillow Image.
113
        
114
        Parameters:
115
        - image: PIL Image, source image to add
116
        """
117
    
118
    def to_pillow(self) -> 'PIL.Image.Image':
119
        """
120
        Convert primary image to Pillow Image.
121
        
122
        Returns:
123
        PIL.Image.Image: Pillow Image object with metadata preserved
124
        """
125
    
126
    def get_aux_image(self, aux_id):
127
        """
128
        Get auxiliary image by ID.
129
        
130
        Parameters:
131
        - aux_id: int, auxiliary image identifier
132
        
133
        Returns:
134
        HeifAuxImage: Auxiliary image object
135
        """
136
    
137
    def __len__(self) -> int:
138
        """Return number of images in container."""
139
    
140
    def __iter__(self):
141
        """Iterate over all images in container."""
142
    
143
    def __getitem__(self, index) -> 'HeifImage':
144
        """Get image by index."""
145
    
146
    def __delitem__(self, index):
147
        """Delete image by index."""
148
```
149

150
Usage example:
151
```python
152
import pillow_heif
153

154
# Create from file
155
heif_file = pillow_heif.open_heif("multi_image.heic")
156

157
# Access primary image properties
158
print(f"Primary image: {heif_file.size} {heif_file.mode}")
159
print(f"Has alpha: {heif_file.has_alpha}")
160
print(f"MIME type: {heif_file.mimetype}")
161

162
# Container operations
163
print(f"Total images: {len(heif_file)}")
164
for i, image in enumerate(heif_file):
165
    print(f"Image {i}: {image.size}")
166

167
# Add new image
168
heif_file.add_frombytes("RGB", (100, 100), b"..." * 30000)
169

170
# Save modified file
171
heif_file.save("output.heic", quality=95)
172
```
173

174
### HeifImage - Individual Image
175

176
Represents a single image within a HeifFile with full access to image data, metadata, and associated auxiliary images.
177

178
```python { .api }
179
class HeifImage:
180
    """
181
    Individual image within a HEIF/AVIF container.
182
    
183
    Properties:
184
    - size: tuple[int, int], image dimensions (width, height)
185
    - mode: str, color mode ('RGB', 'RGBA', 'L', etc.)
186
    - data: bytes, raw image data
187
    - stride: int, bytes per row of image data
188
    - has_alpha: bool, True if image has alpha channel
189
    - premultiplied_alpha: bool, True if alpha is premultiplied
190
    - info: dict, image metadata dictionary
191
    - __array_interface__: dict, NumPy array interface for direct array access
192
    """
193
    
194
    @property
195
    def size(self) -> tuple[int, int]:
196
        """Image dimensions (width, height)."""
197
    
198
    @property
199
    def mode(self) -> str:
200
        """Color mode ('RGB', 'RGBA', 'L', etc.)."""
201
    
202
    @property
203
    def data(self) -> bytes:
204
        """Raw image data."""
205
    
206
    @property
207
    def stride(self) -> int:
208
        """Bytes per row of image data."""
209
    
210
    @property
211
    def has_alpha(self) -> bool:
212
        """True if image has alpha channel."""
213
    
214
    @property
215
    def premultiplied_alpha(self) -> bool:
216
        """True if alpha is premultiplied."""
217
    
218
    @premultiplied_alpha.setter
219
    def premultiplied_alpha(self, value: bool):
220
        """Set premultiplied alpha state."""
221
    
222
    @property
223
    def info(self) -> dict:
224
        """Image metadata dictionary."""
225
    
226
    @property
227
    def __array_interface__(self):
228
        """NumPy array interface for direct array access."""
229
    
230
    def to_pillow(self):
231
        """
232
        Convert image to Pillow Image.
233
        
234
        Returns:
235
        PIL.Image: Pillow Image object with metadata preserved
236
        """
237
    
238
    def get_aux_image(self, aux_id):
239
        """
240
        Get auxiliary image associated with this image.
241
        
242
        Parameters:
243
        - aux_id: int, auxiliary image identifier
244
        
245
        Returns:
246
        HeifAuxImage: Associated auxiliary image
247
        """
248
    
249
    def load(self):
250
        """
251
        Decode image data if not already loaded.
252
        
253
        Notes:
254
        - Called automatically when accessing data property
255
        - Useful for explicit control over decoding timing
256
        """
257
```
258

259
Usage example:
260
```python
261
import pillow_heif
262
import numpy as np
263

264
heif_file = pillow_heif.open_heif("image.heic")
265

266
# Access individual image
267
image = heif_file[0]  # First image
268
print(f"Image size: {image.size}")
269
print(f"Color mode: {image.mode}")
270

271
# Convert to NumPy array using array interface
272
np_array = np.asarray(image)
273
print(f"Array shape: {np_array.shape}")
274

275
# Convert to Pillow for processing
276
pil_image = image.to_pillow()
277
pil_image.show()
278

279
# Access metadata
280
if 'exif' in image.info:
281
    print("EXIF data present")
282
```
283

284
### HeifDepthImage - Depth Information
285

286
Represents depth image data associated with a HeifImage, providing 3D depth information for effects and processing.
287

288
```python { .api }
289
class HeifDepthImage:
290
    """
291
    Depth image associated with a HeifImage.
292
    
293
    Properties:
294
    - size: tuple[int, int], depth image dimensions
295
    - mode: str, depth data mode (typically 'L' for grayscale)
296
    - data: bytes, raw depth data
297
    - stride: int, bytes per row of depth data
298
    - info: dict, depth-specific metadata
299
    """
300
    
301
    @property
302
    def size(self) -> tuple[int, int]:
303
        """Depth image dimensions."""
304
    
305
    @property
306
    def mode(self) -> str:
307
        """Depth data mode (typically 'L' for grayscale)."""
308
    
309
    @property
310
    def data(self) -> bytes:
311
        """Raw depth data."""
312
    
313
    @property
314
    def stride(self) -> int:
315
        """Bytes per row of depth data."""
316
    
317
    @property
318
    def info(self) -> dict:
319
        """Depth-specific metadata."""
320
    
321
    def to_pillow(self):
322
        """
323
        Convert depth image to Pillow Image.
324
        
325
        Returns:
326
        PIL.Image: Pillow Image containing depth information
327
        """
328
    
329
    def load(self):
330
        """
331
        Decode depth data if not already loaded.
332
        """
333
```
334

335
Usage example:
336
```python
337
import pillow_heif
338

339
heif_file = pillow_heif.open_heif("depth_image.heic")
340
image = heif_file[0]
341

342
# Check if image has depth information
343
if hasattr(image, 'depth_images') and image.depth_images:
344
    depth_image = image.depth_images[0]
345
    print(f"Depth image size: {depth_image.size}")
346
    
347
    # Convert to Pillow for visualization
348
    depth_pil = depth_image.to_pillow()
349
    depth_pil.save("depth_map.png")
350
```
351

352
### HeifAuxImage - Auxiliary Images
353

354
Represents auxiliary images associated with a HeifImage, such as alpha masks, thumbnails, or other supplementary data.
355

356
```python { .api }
357
class HeifAuxImage:
358
    """
359
    Auxiliary image associated with a HeifImage.
360
    
361
    Properties:
362
    - size: tuple[int, int], auxiliary image dimensions
363
    - mode: str, color mode of auxiliary data
364
    - data: bytes, raw auxiliary image data
365
    - stride: int, bytes per row of auxiliary data
366
    """
367
    
368
    @property
369
    def size(self) -> tuple[int, int]:
370
        """Auxiliary image dimensions."""
371
    
372
    @property
373
    def mode(self) -> str:
374
        """Color mode of auxiliary data."""
375
    
376
    @property
377
    def data(self) -> bytes:
378
        """Raw auxiliary image data."""
379
    
380
    @property
381
    def stride(self) -> int:
382
        """Bytes per row of auxiliary data."""
383
    
384
    def to_pillow(self):
385
        """
386
        Convert auxiliary image to Pillow Image.
387
        
388
        Returns:
389
        PIL.Image: Pillow Image containing auxiliary data
390
        """
391
    
392
    def load(self):
393
        """
394
        Decode auxiliary data if not already loaded.
395
        """
396
```
397

398
Usage example:
399
```python
400
import pillow_heif
401

402
heif_file = pillow_heif.open_heif("image_with_aux.heic")
403
image = heif_file[0]
404

405
# Access auxiliary images
406
aux_image = image.get_aux_image(1)  # Get auxiliary image by ID
407
if aux_image:
408
    print(f"Auxiliary image size: {aux_image.size}")
409
    aux_pil = aux_image.to_pillow()
410
    aux_pil.save("auxiliary_data.png")
411
```
412

413
## Common Usage Patterns
414

415
### Working with Multi-Image Files
416

417
```python
418
import pillow_heif
419

420
# Open multi-image HEIF file
421
heif_file = pillow_heif.open_heif("burst_photos.heic")
422

423
# Process each image
424
for i, image in enumerate(heif_file):
425
    print(f"Processing image {i+1}/{len(heif_file)}")
426
    pil_image = image.to_pillow()
427
    pil_image.save(f"image_{i+1}.jpg", quality=95)
428

429
# Access specific images
430
primary_image = heif_file[heif_file.primary_index]
431
print(f"Primary image: {primary_image.size}")
432
```
433

434
### Metadata Access
435

436
```python
437
import pillow_heif
438

439
heif_file = pillow_heif.open_heif("image_with_metadata.heic")
440

441
# Access metadata from HeifFile
442
print("File metadata:")
443
for key, value in heif_file.info.items():
444
    print(f"  {key}: {type(value).__name__}")
445

446
# Access metadata from individual images
447
image = heif_file[0]
448
if 'exif' in image.info:
449
    exif_data = image.info['exif']
450
    print(f"EXIF data size: {len(exif_data)} bytes")
451
```
452

453
### NumPy Integration
454

455
```python
456
import pillow_heif
457
import numpy as np
458

459
heif_file = pillow_heif.open_heif("image.heic")
460
image = heif_file[0]
461

462
# Direct NumPy array access
463
np_array = np.asarray(image)
464
print(f"Array shape: {np_array.shape}")
465
print(f"Data type: {np_array.dtype}")
466

467
# Process with NumPy
468
processed = np_array * 0.8  # Darken image
469
processed = processed.astype(np.uint8)
470

471
# Convert back to HeifFile
472
new_heif = pillow_heif.from_bytes(
473
    mode=image.mode,
474
    size=image.size,
475
    data=processed.tobytes()
476
)
477
```