0
# ExifRead
1

2
A pure Python library for extracting EXIF metadata from digital image files. ExifRead provides comprehensive metadata extraction from TIFF, JPEG, WebP, and HEIC image formats without external dependencies, making it ideal for photo analysis, digital asset management, and metadata processing applications.
3

4
## Package Information
5

6
- **Package Name**: ExifRead
7
- **Language**: Python
8
- **Installation**: `pip install exifread`
9

10
## Core Imports
11

12
```python
13
import exifread
14
```
15

16
For GPS coordinate extraction:
17

18
```python
19
from exifread.utils import get_gps_coords
20
```
21

22
For accessing specific classes and utilities:
23

24
```python
25
from exifread.classes import IfdTag, ExifHeader
26
from exifread.utils import Ratio
27
```
28

29
## Basic Usage
30

31
```python
32
import exifread
33

34
# Open image file for reading (binary mode)
35
with open('image.jpg', 'rb') as f:
36
    # Extract EXIF tags
37
    tags = exifread.process_file(f)
38

39
# Iterate through tags
40
for tag_name, tag_value in tags.items():
41
    if tag_name not in ('JPEGThumbnail', 'TIFFThumbnail', 'EXIF MakerNote'):
42
        print(f"{tag_name}: {tag_value}")
43

44
# Access specific tags
45
if 'EXIF DateTimeOriginal' in tags:
46
    date_taken = tags['EXIF DateTimeOriginal']
47
    print(f"Photo taken: {date_taken}")
48

49
if 'Image Orientation' in tags:
50
    orientation = tags['Image Orientation']
51
    print(f"Orientation: {orientation}")
52
```
53

54
## Architecture
55

56
ExifRead uses a layered architecture for processing image metadata:
57

58
- **Process Function**: `process_file()` serves as the main entry point, detecting file format and coordinating extraction
59
- **Format Handlers**: Specialized parsers for TIFF, JPEG, WebP, and HEIC formats handle format-specific metadata location
60
- **EXIF Header**: `ExifHeader` class manages IFD (Image File Directory) parsing and tag extraction
61
- **Tag System**: `IfdTag` objects represent individual metadata tags with values and type information
62
- **MakerNote Decoders**: Camera-specific parsers for proprietary metadata from Canon, Nikon, Olympus, Fujifilm, Casio, and Apple
63

64
This design enables comprehensive metadata extraction while maintaining compatibility across image formats and camera manufacturers.
65

66
## Capabilities
67

68
### Core EXIF Processing
69

70
Main functionality for extracting EXIF metadata from image files, including format detection, tag parsing, and thumbnail extraction. Supports all major image formats with comprehensive error handling.
71

72
```python { .api }
73
def process_file(fh, stop_tag='UNDEF', details=True, strict=False, debug=False, truncate_tags=True, auto_seek=True):
74
    """
75
    Process an image file and extract EXIF metadata.
76
    
77
    Parameters:
78
    - fh: Open file handle (binary mode)
79
    - stop_tag: Tag name to stop processing at
80
    - details: Process MakerNotes and thumbnails
81
    - strict: Strict mode (stop on errors)
82
    - debug: Enable debug output
83
    - truncate_tags: Truncate long tag values
84
    - auto_seek: Automatically seek to beginning
85
    
86
    Returns:
87
    dict: Dictionary of IfdTag objects
88
    """
89
```
90

91
[Core Processing](./core-processing.md)
92

93
### Tag Data Structures
94

95
Classes and objects for representing EXIF metadata, including individual tags, file headers, and specialized data types like ratios for camera settings.
96

97
```python { .api }
98
class IfdTag:
99
    """Represents an individual EXIF tag with value and metadata."""
100
    
101
class ExifHeader:
102
    """Handles EXIF header parsing and processing."""
103
    
104
class Ratio:
105
    """Represents rational numbers for EXIF values."""
106
```
107

108
[Data Structures](./data-structures.md)
109

110
### Utility Functions
111

112
Helper functions for processing extracted metadata, including GPS coordinate conversion, string handling, and format compatibility utilities.
113

114
```python { .api }
115
def get_gps_coords(tags):
116
    """Extract GPS coordinates from EXIF tags."""
117
    
118
def make_string(seq):
119
    """Convert sequence to printable string."""
120
    
121
def make_string_uc(seq):
122
    """Handle user comment string encoding."""
123
```
124

125
[Utilities](./utilities.md)
126

127
### Command Line Interface
128

129
Command-line tool for extracting and displaying EXIF metadata from image files with various processing options and output formats.
130

131
```python { .api }
132
def main():
133
    """Command line entry point for EXIF extraction."""
134
    
135
def get_args():
136
    """Parse command line arguments."""
137
```
138

139
[Command Line](./cli.md)
140

141
### Exception Handling
142

143
Exception classes for handling various error conditions during EXIF processing, including invalid data, missing metadata, and format-specific errors.
144

145
```python { .api }
146
class InvalidExif(Exception):
147
    """Raised for invalid EXIF data."""
148
    
149
class ExifNotFound(Exception):
150
    """Raised when no EXIF data found."""
151
```
152

153
[Error Handling](./exceptions.md)
154

155
### HEIC Format Support
156

157
Support for HEIC/HEIF image format with specialized parsing for ISO base media file format. Handles the complex box structure used in Apple's HEIC format to locate and extract EXIF metadata.
158

159
```python { .api }
160
class HEICExifFinder:
161
    """Find and extract EXIF data from HEIC files."""
162
    
163
class WrongBox(Exception):
164
    """HEIC box structure error."""
165
    
166
class NoParser(Exception):
167
    """No parser for HEIC box type."""
168
    
169
class BoxVersion(Exception):
170
    """Unsupported HEIC box version."""
171
    
172
class BadSize(Exception):
173
    """Invalid HEIC box size."""
174
```
175

176
[HEIC Processing](./heic.md)
177

178
### Important Constants
179

180
Core constants and tag definitions used throughout the library for EXIF processing and format specifications.
181

182
```python { .api }
183
DEFAULT_STOP_TAG: str = 'UNDEF'
184
"""Default tag name to stop processing at."""
185

186
FIELD_TYPES: tuple
187
"""EXIF field type definitions as (length, abbreviation, full name) tuples."""
188

189
IGNORE_TAGS: tuple
190
"""Tags to ignore during quick processing mode."""
191

192
EXIF_TAGS: dict
193
"""Standard EXIF tag definitions mapping tag IDs to names."""
194

195
GPS_TAGS: dict
196
"""GPS-specific EXIF tags mapping tag IDs to names."""
197

198
INTEROP_TAGS: dict
199
"""Interoperability EXIF tags mapping tag IDs to names."""
200
```
201

202
### MakerNote Support
203

204
Camera-specific metadata parsing for proprietary manufacturer tags. Supports MakerNote formats from major camera manufacturers including Canon, Nikon, Olympus, Fujifilm, Casio, and Apple devices.
205

206
```python { .api }
207
# MakerNote modules available:
208
# exifread.tags.makernote.canon - Canon camera tags
209
# exifread.tags.makernote.nikon - Nikon camera tags  
210
# exifread.tags.makernote.olympus - Olympus camera tags
211
# exifread.tags.makernote.fujifilm - Fujifilm camera tags
212
# exifread.tags.makernote.casio - Casio camera tags
213
# exifread.tags.makernote.apple - Apple device tags
214
```
215

216
### Logging System
217

218
Configurable logging system with debug output, color support, and structured error reporting for troubleshooting metadata extraction issues.
219

220
```python { .api }
221
def get_logger():
222
    """Get logger instance for ExifRead."""
223
    
224
def setup_logger(debug, color):
225
    """Configure logger with debug and color options."""
226
```
227

228
[Logging](./logging.md)