0
# Pillow-HEIF
1

2
Python interface for libheif library providing comprehensive HEIF/AVIF image processing with both standalone library and Pillow plugin capabilities. Supports 8/10/12-bit images, full metadata handling (EXIF/XMP/IPTC), multi-image files, thumbnails, depth images, and auxiliary images.
3

4
## Package Information
5

6
- **Package Name**: pillow-heif
7
- **Language**: Python
8
- **Installation**: `pip install pillow-heif`
9
- **Python Version**: 3.9 - 3.13
10

11
## Core Imports
12

13
```python
14
import pillow_heif
15
```
16

17
For Pillow plugin integration:
18

19
```python
20
from pillow_heif import register_heif_opener
21
register_heif_opener()
22
```
23

24
## Basic Usage
25

26
### Standalone Library Usage
27

28
```python
29
import pillow_heif
30

31
# Check if file is supported
32
if pillow_heif.is_supported("image.heic"):
33
    # Open HEIF file
34
    heif_file = pillow_heif.open_heif("image.heic")
35
    
36
    # Access image properties
37
    print(f"Size: {heif_file.size}")
38
    print(f"Mode: {heif_file.mode}")
39
    print(f"Has alpha: {heif_file.has_alpha}")
40
    
41
    # Convert to Pillow Image
42
    pil_image = heif_file.to_pillow()
43
    
44
    # Save as HEIF
45
    heif_file.save("output.heic", quality=90)
46
```
47

48
### Pillow Plugin Usage
49

50
```python
51
from PIL import Image
52
from pillow_heif import register_heif_opener
53

54
# Register HEIF support with Pillow
55
register_heif_opener()
56

57
# Use Pillow normally with HEIF support
58
im = Image.open("image.heic")
59
im = im.rotate(13)
60
im.save("rotated_image.heic", quality=90)
61
```
62

63
## Architecture
64

65
Pillow-HEIF provides two main usage modes:
66

67
- **Standalone Library**: Direct access to HEIF/AVIF functionality through HeifFile and HeifImage classes
68
- **Pillow Plugin**: Seamless integration with PIL/Pillow, adding HEIF support to existing workflows
69

70
The library is built around several core concepts:
71
- **HeifFile**: Container for one or more HEIF/AVIF images with metadata
72
- **HeifImage**: Individual images within a file with processing capabilities  
73
- **Auxiliary Images**: Additional data like depth maps, thumbnails, alpha masks
74
- **Metadata Support**: Complete EXIF, XMP, and IPTC handling
75
- **Multi-format Support**: Both HEIF and AVIF with various bit depths (8/10/12-bit)
76

77
## Capabilities
78

79
### File Operations
80

81
Core functionality for opening, reading, and validating HEIF/AVIF files. Includes support for format detection, multi-image files, and various opening modes.
82

83
```python { .api }
84
def open_heif(fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs) -> HeifFile: ...
85
def read_heif(fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs) -> HeifFile: ...
86
def is_supported(fp) -> bool: ...
87
```
88

89
[File Operations](./file-operations.md)
90

91
### Image Classes
92

93
Main container and image classes for handling HEIF/AVIF data, including primary images, depth images, and auxiliary images with comprehensive metadata access.
94

95
```python { .api }
96
class HeifFile: ...
97
class HeifImage: ...
98
class HeifDepthImage: ...
99
class HeifAuxImage: ...
100
```
101

102
[Image Classes](./image-classes.md)
103

104
### Encoding
105

106
Functions for creating HEIF/AVIF files from raw data, Pillow images, or other sources with extensive encoding options and quality control.
107

108
```python { .api }
109
def encode(mode, size, data, fp, **kwargs): ...
110
def from_pillow(pil_image) -> HeifFile: ...
111
def from_bytes(mode, size, data, **kwargs) -> HeifFile: ...
112
```
113

114
[Encoding](./encoding.md)
115

116
### Pillow Integration
117

118
Plugin functionality that adds seamless HEIF/AVIF support to Pillow, including the HeifImageFile class and registration functions.
119

120
```python { .api }
121
def register_heif_opener(**kwargs): ...
122
class HeifImageFile: ...
123
```
124

125
[Pillow Integration](./pillow-integration.md)
126

127
### Metadata and Utilities
128

129
Helper functions for MIME type detection, orientation handling, library information, and plugin loading for extended format support.
130

131
```python { .api }
132
def get_file_mimetype(fp) -> str: ...
133
def set_orientation(info) -> int | None: ...
134
def libheif_version() -> str: ...
135
def libheif_info() -> dict: ...
136
```
137

138
[Metadata and Utilities](./metadata-utilities.md)
139

140
## Configuration Options
141

142
Runtime configuration variables that control library behavior:
143

144
```python { .api }
145
# Available in pillow_heif.options module
146
DECODE_THREADS = 4  # Threading for decoding
147
THUMBNAILS = True  # Enable thumbnail support
148
DEPTH_IMAGES = True  # Enable depth image support
149
AUX_IMAGES = True  # Enable auxiliary image support
150
QUALITY = None  # Default encoding quality
151
SAVE_HDR_TO_12_BIT = False  # HDR bit depth preference
152
SAVE_NCLX_PROFILE = True  # Color profile handling
153
PREFERRED_ENCODER = {"AVIF": "", "HEIF": ""}  # Encoder preferences
154
PREFERRED_DECODER = {"AVIF": "", "HEIF": ""}  # Decoder preferences
155
```
156

157
## Color Space and Metadata Types
158

159
```python { .api }
160
# Enum types for color space handling
161
class HeifColorPrimaries(IntEnum): ...
162
class HeifTransferCharacteristics(IntEnum): ...
163
class HeifMatrixCoefficients(IntEnum): ...
164
class HeifDepthRepresentationType(IntEnum): ...
165
```
166

167
## Error Handling
168

169
The library handles various error conditions gracefully:
170

171
- **Unsupported files**: Use `is_supported()` to check before opening
172
- **Corrupted data**: IOError or specific libheif exceptions raised
173
- **Missing dependencies**: Import errors for optional features
174
- **Memory limits**: Configurable security limits via `DISABLE_SECURITY_LIMITS`