0
# File Operations
1

2
Core functionality for opening, reading, and validating HEIF/AVIF files. These functions provide the primary interface for working with HEIF/AVIF image files, supporting format detection, multi-image containers, and various processing modes.
3

4
## Capabilities
5

6
### Opening HEIF Files
7

8
Opens a HEIF/AVIF file for reading without automatically decoding all images. Provides lazy loading for efficient memory usage with multi-image files.
9

10
```python { .api }
11
def open_heif(fp, convert_hdr_to_8bit: bool = True, bgr_mode: bool = False, **kwargs) -> HeifFile:
12
    """
13
    Open a HEIF/AVIF file for reading.
14
    
15
    Parameters:
16
    - fp: file path (str) or file-like object
17
    - convert_hdr_to_8bit: bool, convert HDR images to 8-bit (default: True)
18
    - bgr_mode: bool, return BGR pixel order instead of RGB (default: False)
19
    - **kwargs: additional options for decoding
20
    
21
    Returns:
22
    HeifFile: Container object with access to all images in the file
23
    
24
    Raises:
25
    IOError: If file cannot be opened or is not a valid HEIF/AVIF file
26
    """
27
```
28

29
Usage example:
30
```python
31
import pillow_heif
32

33
# Open HEIF file with default settings
34
heif_file = pillow_heif.open_heif("image.heic")
35

36
# Open with HDR preservation
37
heif_file = pillow_heif.open_heif("hdr_image.heic", convert_hdr_to_8bit=False)
38

39
# Open for OpenCV usage (BGR order)
40
heif_file = pillow_heif.open_heif("image.heic", bgr_mode=True)
41
```
42

43
### Reading HEIF Files
44

45
Opens and immediately decodes all images in a HEIF/AVIF file. More memory intensive but provides immediate access to all image data.
46

47
```python { .api }
48
def read_heif(fp, convert_hdr_to_8bit: bool = True, bgr_mode: bool = False, **kwargs) -> HeifFile:
49
    """
50
    Open and decode all images in a HEIF/AVIF file.
51
    
52
    Parameters:
53
    - fp: file path (str) or file-like object
54
    - convert_hdr_to_8bit: bool, convert HDR images to 8-bit (default: True)
55
    - bgr_mode: bool, return BGR pixel order instead of RGB (default: False)
56
    - **kwargs: additional options for decoding
57
    
58
    Returns:
59
    HeifFile: Container object with all images decoded and ready for use
60
    
61
    Raises:
62
    IOError: If file cannot be opened or decoded
63
    """
64
```
65

66
Usage example:
67
```python
68
import pillow_heif
69

70
# Read entire HEIF file into memory
71
heif_file = pillow_heif.read_heif("multi_image.heic")
72

73
# Access all images immediately
74
for i, image in enumerate(heif_file):
75
    print(f"Image {i}: {image.size} {image.mode}")
76
```
77

78
### Format Support Detection
79

80
Checks if a file or file-like object contains supported HEIF/AVIF data. Fast format detection without full file parsing.
81

82
```python { .api }
83
def is_supported(fp) -> bool:
84
    """
85
    Check if file contains supported HEIF/AVIF data.
86
    
87
    Parameters:
88
    - fp: file path (str) or file-like object
89
    
90
    Returns:
91
    bool: True if file is supported HEIF/AVIF format, False otherwise
92
    
93
    Notes:
94
    - Does not validate full file integrity, only checks format signature
95
    - Returns False for corrupted files that may have valid headers
96
    """
97
```
98

99
Usage example:
100
```python
101
import pillow_heif
102

103
# Check before processing
104
if pillow_heif.is_supported("unknown_format.heic"):
105
    heif_file = pillow_heif.open_heif("unknown_format.heic")
106
    # Process file
107
else:
108
    print("File format not supported")
109

110
# Batch processing with format checking
111
import os
112
for filename in os.listdir("images/"):
113
    filepath = os.path.join("images", filename)
114
    if pillow_heif.is_supported(filepath):
115
        heif_file = pillow_heif.open_heif(filepath)
116
        # Process supported files
117
```
118

119
## Common Parameters
120

121
### File Path Handling
122

123
All functions accept either file paths as strings or file-like objects:
124

125
```python
126
# File path
127
heif_file = pillow_heif.open_heif("/path/to/image.heic")
128

129
# File-like object
130
with open("image.heic", "rb") as f:
131
    heif_file = pillow_heif.open_heif(f)
132

133
# BytesIO object
134
from io import BytesIO
135
heif_file = pillow_heif.open_heif(BytesIO(heif_data))
136
```
137

138
### HDR and Bit Depth Handling
139

140
```python
141
# Preserve HDR data (10/12-bit images)
142
heif_file = pillow_heif.open_heif("hdr.heic", convert_hdr_to_8bit=False)
143
print(f"Original bit depth preserved: {heif_file.mode}")
144

145
# Convert HDR to 8-bit for compatibility
146
heif_file = pillow_heif.open_heif("hdr.heic", convert_hdr_to_8bit=True)
147
print(f"Converted to 8-bit: {heif_file.mode}")
148
```
149

150
### Color Order Options
151

152
```python
153
# Standard RGB order for most applications
154
heif_file = pillow_heif.open_heif("image.heic", bgr_mode=False)
155

156
# BGR order for OpenCV compatibility
157
heif_file = pillow_heif.open_heif("image.heic", bgr_mode=True)
158
import cv2
159
np_array = np.asarray(heif_file)
160
cv2.imwrite("output.png", np_array)  # Direct OpenCV usage
161
```
162

163
## Error Handling
164

165
```python
166
import pillow_heif
167

168
try:
169
    if pillow_heif.is_supported("image.heic"):
170
        heif_file = pillow_heif.open_heif("image.heic")
171
        # Process file
172
    else:
173
        print("Unsupported file format")
174
except IOError as e:
175
    print(f"Error opening file: {e}")
176
except Exception as e:
177
    print(f"Unexpected error: {e}")
178
```