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
```