OpenEXR Python Bindings

Warnings

• breaking The `openexr` package is the official Python 3 binding for OpenEXR 3.x, replacing the older `PyOpenEXR` and `PyImath` packages which were tied to OpenEXR 2.x. Users migrating from older setups will find significant API differences and different import paths. Do not mix `openexr` with `PyOpenEXR`.
  Fix: Rewrite code to use the new `openexr` API (e.g., `openexr.InputFile` instead of `OpenEXR.InputFile`). Ensure `pip install openexr` and potentially `pip install imath` are used, not `pip install PyOpenEXR PyImath`.
• gotcha Installing `openexr` from source can be complex due to its underlying C++ dependencies (OpenEXR, Imath, zlib, etc.). Pre-built wheels are typically available on PyPI for common platforms, but if a wheel isn't available for your specific Python version/OS, a robust C++ build environment (including `cmake`) is required.
  Fix: Prioritize `pip install openexr` to leverage pre-built wheels. If building from source, ensure `cmake` and all necessary C++ development headers for OpenEXR and its dependencies are installed on your system.
• gotcha While `openexr` provides EXR file I/O, `Imath` (vectors, matrices, boxes) is typically accessed via the separate `imath` Python package. Though `openexr`'s internal C++ libraries use Imath, its Python bindings do not fully expose all Imath types directly under the `openexr` namespace.
  Fix: Always `import Imath` separately if you need to create or manipulate Imath-specific types (e.g., `Imath.V3f`, `Imath.Box2i`) in your Python code, and ensure the `imath` package is installed (`pip install imath`).
• gotcha Pixel data read from `openexr` channels are returned as raw `bytes` objects. These must be converted to `numpy.ndarray` for practical manipulation, requiring careful handling of `dtype` (e.g., `np.float16` for `HALF`, `np.float32` for `FLOAT`) and `reshape` to the correct image dimensions.
  Fix: When reading, use `np.frombuffer(raw_bytes, dtype=...).reshape(...)`. When writing, convert your `numpy` arrays to bytes using `array.tobytes()` and ensure the `PixelType` in the `openexr.Header` matches your data's `dtype`.
• gotcha Multiple recent patch releases (e.g., 3.4.9, 3.3.9, 3.2.7) have addressed significant security vulnerabilities, including heap out-of-bounds writes and integer overflows, which could lead to crashes or arbitrary code execution when processing malformed EXR files.
  Fix: Always keep your `openexr` installation updated to the latest patch release (e.g., `pip install --upgrade openexr`) to mitigate known security risks, especially when dealing with EXR files from untrusted sources.

Install

• pip install openexr Install stable version

Imports

• openexr

  import openexr

• Imath

  import Imath

  Imath is a separate, but closely related, package. While OpenEXR provides its core functionality, Imath types are best accessed from the dedicated 'imath' package.

Quickstart

This quickstart demonstrates writing a simple RGB image with `HALF` precision to an EXR file and then reading the red channel back. It utilizes `numpy` for data manipulation, which is standard practice when working with image pixel data in `openexr`. Ensure you have `numpy` and `imath` installed (`pip install numpy imath`).

import openexr
import Imath
import numpy as np

# Define image properties
width = 256
height = 256
half_channels = {'R': Imath.ChannelList().add('R', Imath.PixelType(Imath.PixelType.HALF)),
                 'G': Imath.ChannelList().add('G', Imath.PixelType(Imath.PixelType.HALF)),
                 'B': Imath.ChannelList().add('B', Imath.PixelType(Imath.PixelType.HALF))}

# Create some dummy data (e.g., a simple gradient)
x = np.linspace(0, 1, width)
y = np.linspace(0, 1, height)
R = np.outer(y, x).astype(np.float16)
G = np.outer(y, 1-x).astype(np.float16)
B = np.outer(1-y, x).astype(np.float16)

# Write an EXR file
output_filename = 'example.exr'
header = openexr.Header(width, height)
# Ensure correct channel types and data window if writing half data
# header['channels'] = half_channels 
# The above is for explicit channel list. For simplicity, let's use default half for RGB.

file_out = openexr.OutputFile(output_filename, header)
file_out.writePixels({'R': R.tobytes(), 'G': G.tobytes(), 'B': B.tobytes()})
file_out.close()
print(f"Written {output_filename}")

# Read the EXR file
file_in = openexr.InputFile(output_filename)
header_in = file_in.header()
data_window = header_in['dataWindow']
dw = Imath.Box2i(data_window)
size = (dw.max.x - dw.min.x + 1, dw.max.y - dw.min.y + 1)

# Read 'R' channel data as bytes and convert to numpy array
r_channel_bytes = file_in.channel('R', Imath.PixelType(Imath.PixelType.HALF))
r_data = np.frombuffer(r_channel_bytes, dtype=np.float16).reshape(size[1], size[0])

print(f"Read R channel data shape: {r_data.shape}")
print(f"First few R values: {r_data.flatten()[:5]}")
file_in.close()