0
# OpenEXR
1

2
Professional-grade EXR image format library for high-dynamic-range (HDR) scene-linear image data. OpenEXR provides comprehensive support for multi-channel images, deep compositing, multi-part files, and advanced compression methods used extensively in visual effects, animation, and professional photography workflows.
3

4
## Package Information
5

6
- **Package Name**: OpenEXR
7
- **Package Type**: pypi
8
- **Language**: Python (with C++ backend)
9
- **Installation**: `pip install OpenEXR`
10

11
## Core Imports
12

13
```python
14
import OpenEXR
15
```
16

17
For working with image data arrays:
18

19
```python
20
import OpenEXR
21
import numpy as np
22
```
23

24
For geometric types and metadata:
25

26
```python
27
from OpenEXR import Imath
28
```
29

30
## Basic Usage
31

32
```python
33
import OpenEXR
34
import numpy as np
35

36
# Create image data
37
height, width = 480, 640
38
rgb_data = np.random.rand(height, width, 3).astype('f')
39

40
# Write EXR file
41
header = {
42
    "compression": OpenEXR.ZIP_COMPRESSION,
43
    "type": OpenEXR.scanlineimage
44
}
45
channels = {"RGB": rgb_data}
46

47
with OpenEXR.File(header, channels) as outfile:
48
    outfile.write("output.exr")
49

50
# Read EXR file
51
with OpenEXR.File("output.exr") as infile:
52
    header = infile.header()
53
    channels = infile.channels()
54
    rgb_pixels = channels["RGB"].pixels
55
    
56
    print(f"Image size: {infile.width()} x {infile.height()}")
57
    print(f"Channels: {list(channels.keys())}")
58
```
59

60
## Architecture
61

62
OpenEXR uses a layered architecture optimized for professional image workflows:
63

64
- **File Layer**: High-level file I/O with context management and multi-part support
65
- **Part Layer**: Individual image components within multi-part files (beauty, depth, motion vectors, etc.)
66
- **Channel Layer**: Named data channels with flexible pixel types and subsampling
67
- **Metadata Layer**: Extensible header attributes for workflow information
68
- **Compression Layer**: Multiple algorithms optimized for different content types
69
- **Core Layer**: C++ backend providing high-performance encoding/decoding
70

71
This design enables OpenEXR's role as the standard for VFX and animation pipelines, supporting complex compositing workflows, HDR color spaces, and massive image resolutions with efficient storage and access patterns.
72

73
## Capabilities
74

75
### File I/O Operations
76

77
Primary interfaces for reading and writing EXR files, including scanline and tiled formats, with support for streaming operations and multi-threading.
78

79
```python { .api }
80
class File:
81
    def __init__(self, filename: str, separate_channels: bool = False, header_only: bool = False): ...
82
    def __init__(self, header: dict, channels: dict): ...
83
    def __init__(self, parts: list): ...
84
    
85
    def __enter__(self): ...
86
    def __exit__(self, *args): ...
87
    
88
    def header(self, part_index: int = 0) -> dict: ...
89
    def channels(self, part_index: int = 0) -> dict: ...
90
    def write(self, filename: str) -> None: ...
91
    
92
    def width(self, part_index: int = 0) -> int: ...
93
    def height(self, part_index: int = 0) -> int: ...
94
    
95
    parts: list  # List of Part objects for multi-part files
96
```
97

98
[File I/O Operations](./file-io.md)
99

100
### Image Data Structures
101

102
Channel-based image representation with support for arbitrary pixel types, subsampling, and deep compositing data structures.
103

104
```python { .api }
105
class Channel:
106
    def __init__(self, name: str = None, pixels: np.ndarray = None, 
107
                 xSampling: int = 1, ySampling: int = 1, pLinear: bool = False): ...
108
    def pixelType(self) -> int: ...
109
    
110
    name: str           # Channel name
111
    xSampling: int      # Horizontal subsampling factor
112
    ySampling: int      # Vertical subsampling factor
113
    pLinear: bool       # Premultiplied linear flag
114
    pixels: np.ndarray  # Pixel data array
115

116
class Part:
117
    def __init__(self, header: dict, channels: dict, name: str): ...
118
    def name(self) -> str: ...
119
    def shape(self) -> tuple: ...
120
    def width(self) -> int: ...
121
    def height(self) -> int: ...
122
    def compression(self) -> int: ...
123
    def type(self) -> int: ...
124
    def typeString(self) -> str: ...
125
    
126
    header: dict    # Part metadata
127
    channels: dict  # Channel data
128
```
129

130
[Image Data Structures](./image-data.md)
131

132
### Metadata and Headers
133

134
Extensible attribute system for storing image metadata, including standard attributes for color spaces, camera data, and custom application-specific information.
135

136
```python { .api }
137
# Standard header attributes
138
header = {
139
    "compression": int,         # Compression method
140
    "type": int,               # Image type (scanline/tiled/deep)
141
    "dataWindow": tuple,       # Pixel data bounds
142
    "displayWindow": tuple,    # Display bounds
143
    "pixelAspectRatio": float, # Pixel aspect ratio
144
    "screenWindowCenter": tuple, # Screen window center
145
    "screenWindowWidth": float,  # Screen window width
146
}
147
```
148

149
[Metadata and Headers](./metadata.md)
150

151
### Advanced Features
152

153
Multi-part files, deep compositing images, advanced compression methods, and tiled storage for high-performance random access.
154

155
```python { .api }
156
# Multi-part files
157
parts = [
158
    OpenEXR.Part(beauty_header, beauty_channels, "beauty"),
159
    OpenEXR.Part(depth_header, depth_channels, "depth"),
160
    OpenEXR.Part(motion_header, motion_channels, "motion")
161
]
162

163
# Compression constants
164
OpenEXR.NO_COMPRESSION     # No compression
165
OpenEXR.ZIP_COMPRESSION    # ZIP lossless compression
166
OpenEXR.PIZ_COMPRESSION    # PIZ wavelet compression
167
OpenEXR.DWAA_COMPRESSION   # DWAA lossy compression
168
```
169

170
[Advanced Features](./advanced-features.md)
171

172
### C++ API Reference
173

174
Low-level C++ interface for maximum performance, custom integrations, and advanced use cases requiring direct control over encoding/decoding operations.
175

176
```cpp { .api }
177
// Primary C++ classes
178
class InputFile;               // Scanline input
179
class OutputFile;             // Scanline output
180
class TiledInputFile;         // Tiled input
181
class TiledOutputFile;        // Tiled output
182
class MultiPartInputFile;     // Multi-part input
183
class MultiPartOutputFile;    // Multi-part output
184
```
185

186
[C++ API Reference](./cpp-api.md)
187

188
## Types
189

190
```python { .api }
191
# Pixel type constants
192
OpenEXR.UINT: int    # 32-bit unsigned integer
193
OpenEXR.HALF: int    # 16-bit floating point
194
OpenEXR.FLOAT: int   # 32-bit floating point
195

196
# Compression method constants  
197
OpenEXR.NO_COMPRESSION: int
198
OpenEXR.RLE_COMPRESSION: int
199
OpenEXR.ZIPS_COMPRESSION: int
200
OpenEXR.ZIP_COMPRESSION: int
201
OpenEXR.PIZ_COMPRESSION: int
202
OpenEXR.PXR24_COMPRESSION: int
203
OpenEXR.B44_COMPRESSION: int
204
OpenEXR.B44A_COMPRESSION: int
205
OpenEXR.DWAA_COMPRESSION: int
206
OpenEXR.DWAB_COMPRESSION: int
207
OpenEXR.HTJ2K256_COMPRESSION: int
208
OpenEXR.HTJ2K32_COMPRESSION: int
209

210
# Line order constants
211
OpenEXR.INCREASING_Y: int    # Top to bottom
212
OpenEXR.DECREASING_Y: int    # Bottom to top
213
OpenEXR.RANDOM_Y: int        # Random (tiled only)
214

215
# Image type constants
216
OpenEXR.scanlineimage: int   # Scanline format
217
OpenEXR.tiledimage: int      # Tiled format
218
OpenEXR.deepscanline: int    # Deep scanline format
219
OpenEXR.deeptile: int        # Deep tiled format
220

221
# Level mode constants
222
OpenEXR.ONE_LEVEL: int       # Single resolution level
223
OpenEXR.MIPMAP_LEVELS: int   # Mipmap levels
224
OpenEXR.RIPMAP_LEVELS: int   # Ripmap levels
225

226
# Level rounding mode constants  
227
OpenEXR.ROUND_DOWN: int      # Round down to lower level
228
OpenEXR.ROUND_UP: int        # Round up to higher level
229

230
# Environment map type constants
231
OpenEXR.ENVMAP_LATLONG: int  # Latitude/longitude mapping
232
OpenEXR.ENVMAP_CUBE: int     # Cube face mapping
233

234
# Utility Classes
235
class KeyCode:
236
    """Motion picture film characteristics."""
237
    def __init__(self, filmMfcCode: int = 0, filmType: int = 0, prefix: int = 0,
238
                 count: int = 0, perfOffset: int = 0, perfsPerFrame: int = 0, perfsPerCount: int = 0): ...
239
    
240
    filmMfcCode: int    # Film manufacturer code
241
    filmType: int       # Film type code  
242
    prefix: int         # Prefix
243
    count: int          # Count
244
    perfOffset: int     # Perforation offset
245
    perfsPerFrame: int  # Perforations per frame
246
    perfsPerCount: int  # Perforations per count
247

248
class TimeCode:
249
    """SMPTE time and control code."""
250
    def __init__(self, hours: int = 0, minutes: int = 0, seconds: int = 0, frame: int = 0,
251
                 dropFrame: bool = False, colorFrame: bool = False, fieldPhase: bool = False,
252
                 bgf0: bool = False, bgf1: bool = False, bgf2: bool = False,
253
                 binaryGroup1: int = 0, binaryGroup2: int = 0, binaryGroup3: int = 0,
254
                 binaryGroup4: int = 0, binaryGroup5: int = 0, binaryGroup6: int = 0,
255
                 binaryGroup7: int = 0, binaryGroup8: int = 0): ...
256
    
257
    hours: int          # Hours (0-23)
258
    minutes: int        # Minutes (0-59)
259
    seconds: int        # Seconds (0-59)
260
    frame: int          # Frame number
261
    dropFrame: bool     # Drop frame flag
262
    colorFrame: bool    # Color frame flag
263
    fieldPhase: bool    # Field phase flag
264

265
class Rational:
266
    """Rational number representation."""
267
    def __init__(self, n: int, d: int): ...
268
    
269
    n: int  # Numerator
270
    d: int  # Denominator
271
```